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Preface 


This manual gives you conceptual information 
about using the 5110 with the APL language. 
Before using this manual, you should understand 
the information in the IBM 5110 APL Introduction, 
SA21-9301, especially: 

• How to enter data from the keyboard 

• How APL functions work with one or two 
arguments 

• How to create your own user-defined functions 
using the built-in APL functions 

This manual is intended to be used with the IBM 
5110 APL Reference Manual, SA21-9303; that is, 
this manual gives you information about using the 
5110 system with the APL language for 
information processing. The major topics are: 

• Computer concepts for data processsing 
(Chapter 1) 

• An approach to breaking your application into 
small parts to make programming easier 
(Chapter 2) 

• Elements of the APL language and example APL 
user-defined functions used for information 
processing (Chapter 3) 

• Controlling the information in the active 
workspace (Chapter 4) 

• Using uppercase and lowercase characters, 
scrolling the display screen up or down, and 
sounding the audible alarm (Chapter 5) 

• Creating, using, and maintaining your library 
(Chapter 6) 

• Using the tape or diskette storage media 
(Chapters 7 and 8) 


• Formatting printed reports and example 
user-defined functions used for formatting 
reports (Chapter 9) 

• Creating and using data files for your business 
applications (Chapter 10) 

• Determining what to do when your program 
doesn't work (Chapter 11) 

This manual is not intended to give you a 
complete description of the syntax and rules 
required for each APL command, function, or 
variable; you must use the 5110 APL Reference 
Manual for this information. 

This manual does not need to be read chapter by 
chapter. Instead, you can read the appropriate 
chapters as required. For example, you might read 
Chapter 9, Printer Control when you need to 
format a report. 

This manual follows the convention that he means 
he or she. 


Prerequisite Publication 

IBM 5110 APL Introduction, SA21-9301 


Related Publications 

IBM 5110 APL Reference Manual, SA21-9303 

IBM 5110 APL Reference Card, GX21-9304 

IBM 5110 Customer Support Functions Reference 
Manual, SA21-9311 
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Chapter 1. Data Processing Concepts 


INTRODUCTION 

The IBM 5110 Models 1 and 2 are multipurpose data processing 
systems with a personal touch. Because of their compact size and 
large-scale capabilities, these systems provide solutions to problems 
for a wide variety of users. As a 5110 user, only you can determine 
the problems to be solved with your system. To help you make these 
determinations, this chapter contains general concepts of data 
processing. You may or may not choose to read this chapter, 
depending on your data processing knowledge and experience. 


CONCEPTS 

What can you expect a computer to do with information? How do you 
get information into a computer? How does a computer know what to 
do with your information? What final results can you expect from a 
computer? This section gives general answers to these questions. 

Today the computer is doing many jobs, from accounting to predicting 
election results to guiding spaceships. It is often looked upon as some 
kind of magical machine, but the computer performs no magic. 
Everything a computer does is dependent on the people who use it 
and the instructions they supply. For every job you want a computer 
to do, you must give a step-by-step procedure (a program) for it to 
follow. This procedure is then stored inside the computer. The 
information you want is processed according to the stored 
instructions. 

A computer can do only a few rather simple things, but it does them 
extremely well. It can retrieve, almost instantly, any item of 
information stored in it. It can compare any two items of information, 
and do any arithmetic operations you want: add, subtract, multiply, or 
divide. It can be instructed to do any combination of these things in 
any sequence you want them done. 

The computer works methodically, doing one thing at a time. When it 
finishes one step, it goes on to the next, then the next, and the next, 
according to instructions. But it performs these steps at an almost 
unbelievable speed until it comes up with the answer you want. 
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The task performed by a computer is called data processing. Data 
processing means that information is handled according to a set of 
rules. Whether you process information by hand or use a computer, 
the requirements of a job remain about the same. You must have 
input, which is the data you want to do something with; you must 
process the data, which is the act of doing something with data 
according to instructions; and you must have output, which is the 
result of your processing. 

To help you understand the 5110 and data processing, let's first look 
at how a clerk might process information for the job of billing. For this 
job, assume the clerk works with the following data: 

o Customer orders 

» Price catalogs 

« Customer records 

9 Accounts receivable records 


9 Inventory files 



The clerk receives a copy of the customer orders after orders are 
shipped. He uses these documents to prepare bills that he sends to 
customers. To prepare the bill, he follows this procedure: 

1. Look up, in a price catalog, the price of each item on the order. 

2. Multiply the price by the quantity shipped. 

3. Add the total price of items to get the total amount of bill. 

4. Check the customer records to see if any special discounts apply, 
and adjust the bills accordingly. 

5. Type the bill. 

6. Adjust the accounts-receivable records to show what the 
customer owes. 

7. Update the inventory records to show the reduced stock. 

For each billing, the clerk follows the same procedure. In computer 
terms, this procedure is his program for doing the job. The customer 
order is his input, the calculating and file updating he does is 
processing, and the results of the processing (the billing and updated 
records) are his output. 

The 5110 can speed up the billing operation and reduce costly errors. 
The order information can be entered from the keyboard; the records 
(such as price lists, customer records, accounts receivable records, 
and inventory files) can be quickly referenced and updated (processed) 
using tape or diskette storage; and the printer can print the billings. 

The parts of the 5110 used for data processing are; 

Input 

• The keyboard from which data is entered into the system. 

• Tape or diskette storage from which data can be read for 
processing. 

Processing 

• The 5110 internal storage, which includes the active workspace. The 
active workspace is where calculations are performed and where 
user-defined functions (programs) and variables are stored. 
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Output 


• The display screen, which displays keyboard input and the results of 
executed expressions br statements. That is, the display screen is a 
means of communication between the system and you. 

• The printer, which prints keyboard input (if specified) and the results 
of executed expressions or statements. This printed output is 
sometimes called hard copy output. 

• The tape or diskette on which data can be stored for future 
processing. 



As mentioned before, a program is a procedure or set of instructions 
you establish for doing a job. These instructions are necessary 
because a computer cannot think for itself. When defining a program 
for the 5110, you can use a programming language called APL. APL is 
a simple-to-use programming language with which you describe how 
you want the 5110 to do a job. Also, in APL, a program is called a 
user-defined function. 

The next chapter presents an approach to analyzing a problem or job 
so that an APL user-defined function can be used to help process 
information. 



Chapter 2. Information Processing 


This chapter presents an approach to dissecting an application so that 
APL user-defined functions can be used to help process the 
information. This approach helps you break down the application into 
manageable parts so that you can apply APL expressions and 
commands to process the information. Breaking the application down 
into manageable parts promotes thoroughness and allows the 
application to be solved (programmed) faster. 


INPUT, PROCESS, AND OUTPUT 

Every application consists of three parts: 

• The input required for processing. 

• The process (APL expressions) required to generate the final result 

• The output, which is the final result 

Each part might consist of one or more APL expressions. In the 
following sections, each part is discussed in more detail. Also, an 
example for finding the compound interest is used to illustrate each 
part. 
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Output 


Because the output or result is the primary reason for a user-defined 
function to exist, considering the output provides the best place to 
start solving a problem. To do this, consider these questions: 

1. What results are required? 

2. How should the results be formatted? 

3. Who uses the results? For example, should the results be 
displayed or printed, or should the results be stored in the active 
workspace, on tape, or on diskette for later use? 

Now, for the compound interest example, assume the answers to 
these questions are: 

1. The amount of interest earned. 

2. The message THE INTEREST EARNED IS: followed by the 
calculated interest earned. 

3. Finance officers will use the displayed results to evaluate 
different plans. 

Once you have answered these questions, you know the purpose of a 
user-defined function. 



Input 


After the output, you should consider what input data is required to 
generate the output. To do this, consider such questions as: 

1. What input is required? 

2. Where does the input come from? 

3. How is the input provided? 

Continuing with the compound interest example, the answers to these 
questions are: 

1. The interest rate, number of years, and principal. 

2. From finance officers who need to know the amount of interest 
earned for different plans. 

3. Through the 5110 keyboard. 

In our example, most of the input data will come from the keyboard; 
however, other ways also exist. For example, some data might be 
permanent and be included within the user-defined function (for 
example, headings and labels). There might also be data that is usually 
constant but, for certain problems, must be changed. This data might 
be coded in the user-defined functions as variables that can be 
modified. And, of course, data might also be from tape or diskette. 

The following list summarizes the input and output considerations so 
far: 

Data Device 


I merest rate Keyboard 

Number of years 

Principal 

THE INTEREST EARNED IS: Display Screen 

The calculated interest earned 


Input 


Output 
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Process 


Your introduction to APL started with APL's processing ability. The 
APL language is designed to do processing with a minimum number of 
instructions. 

Once the input and output are well defined, all of the characteristics 
work together to make the process part the most straightforward. 

For our compound interest example, the process part consists of: 

1. Defining the algorithm used to calculate the compound interest 

2. Using the input to generate the results 

The formula used in this example for the compound interest is: 

Cl = Principal x (1 + .01 x Interest Rate) years 

The APL statements that use the input to generate the results might 
be as follows: 

A<-1+. OlxINTERESTRATE 

B«-A* YEARS 

C<-PRINCIPAL^® 


PUTTING IT ALL TOGETHER 


Now that you have considered the three parts of the application, it is 
time to write your user-defined function. For the compound interest 
example, your user-defined function might look like this: 


V 


I.. A.. 

i:: 3 :j 
\;m-i 


^••PRINCIPAL COMPOUND YEARS, 
A«-l + Q , 01 * INTEREST RATE 
B<-A«‘YEARS 
CI<-PRINGIPALxB 
RfTHE INTEREST EARNED 


The interest rate must be 
assigned to this variable before 
the user-defined function is 
executed. 

. 10 2 tCI 


V 


So far, you have taken a simple application and designed a 
user-defined function to solve it. If the application is larger or more 
complex, a more detailed structure is required. This more detailed 
structure involves expanding each of the three parts (input, process, 
and output) into additional levels of input, process, and output. 
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ADDITIONAL LEVELS OF INPUT, PROCESS, AND OUTPUT 



First Level 


Additional Levels 


The method shown in the previous diagram breaks the first-level 
INPUT, part into manageable parts. Let's continue with the compound 
interest problem and treat the INPUT portion as a separate problem in 
itself. 

First, consider the output of the INPUT portion. Here the output is 
actually the input for the first-level PROCESS portion. In this case, 
assume that the output must be an interest rate not greater than 18%, 
a number of years not greater than 40, and a principal not greater than 
500000.00. 

Next, consider the input for the INPUT portion. The input is the same 
as before (the interest rate, number of years, and principal for which 
the interest earned must be calculated). However, in this case, the 
finance officers might be unfamiliar with the user-defined function; 
therefore, there should be prompting messages telling them what to 
enter. 

Finally, consider the process for the INPUT portion. In this case, the 
processing consists of error checking and validation of ail the input 
data, because you want to make sure that the interest rate is not 
greater than 18%, the number of years is not greater than 40, and the 
principal is not greater than 500000.00 
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Now, taking these considerations into account, the APL statements for 
the first-level input portion might be: 


V R<-EXAMPLE , , 

Cl3 START: ’ENTER THE INTEREST RATE, YEARS, AND PRINCIPAL 

t2:i X«-D 

1:3 :i k ( x 1:1 ::i > 1 e), ( x \: 2 3 > 4 0 >, < x 1 : 3 ::i > 5 0 0 o 0 0 > > / e 1 , e 2 , e 3 

C43 -> PROCESS 

C53 El:’THE INTEREST RATE IS GREATER THAN 18 PERCENT’ 

C63 ^START 

C73 E2:’THE NUMBER OF YEARS IS GREATER THAN 40’ 

C83 -+START 

C93 E3 ' THE PRINCIPAL IS GREATER THAN 500000.00* 

Cl 03 +START 
Cl13 PROCESS; 

V 
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As you break an application down into more manageable parts, you 
might want to have a separate user-defined function for each part. For 
example: 


V R«-INTEREST 


i : i ::i 

R*INPUT 

1:2:1 

Rf-PROCESS R 

1:3:1 

Rf-OUT PUT R 


V 


V XMNPUT 

i::;i::i start: * enter the interest rate, years, and principal 


i:2:i 

xh:j 


i:3:i 

•x <xci: 

l>18> , (Xi:2:i>!•!•()> , (XC33>500000) )/E.1.,E2,E3 

1 : * 1 :i 

♦o 


1 : 5:1 

El:•THE 

INTEREST RATE IS GREATER THAN IS PERCENT 

C6:i 

■♦START 


1 : 7:1 

E2: * THE 

NUMBER OF YEARS IS GREATER THAN *+0' 

t: b:i 

♦START 


r.:9:i 

E3; * THE 

PRINCIPAL IS GREATER THAN 500000,00' 

1 : 1 0 :i 

♦START 



y 


V CI <• PROCESS INPUT; A; B 
am+q , oixiNPUTcn 

i: 2 1 B<-A«iNPU'n:: 2 ::i 

C 33 CI«-INPUTC 33 xB 

V 


V R<-OUT PUT Cl 

r<- 1 the interest earned is: *, .1.0 2 ?ci 
y 
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CONCLUSION 


When programming for an application using the 5110, break the 
application down into manageable parts. To do this, first focus on the 
program output. This is the primary interface to the user. It also 
defines what the real purpose of the program is. Next, consider all the 
input data that is required to generate the output. Finally (and only 
then) plan the actual processing. 

Thinking in this way should help you make the transition from knowing 
the APL language to being able to use the APL language to generate 
user-defined functions for specific applications. 



Chapter 3. APL Language Elements 


In this chapter, the following topics concerning the APL language 
elements are discussed: 

• Variables 

• Data representation 

• Arrays 

• Examples of useful APL statements and user-defined functions 


VARIABLES 

You can store data in the 5110 by assigning it to a variable name. 

* These stored items are called variables. Whenever the variable name 
is used, APL supplies the data associated with that name. A variable 
name can be up to 77 characters in length with no blanks; the first 
character must be alphabetic, and the remaining characters can be any 
combination of alphabetic, and numeric characters. The (assignment 
arrow) is used to assign data to a variable: 

LENGTH*-6 
WIDTH *-8 

A RE A*-LENGTH x WIDTH 


To display the value of a variable, enter the variable name: 


6 

8 


4-8 


LENGTH 

WIDTH 


AREA 


APL Language Elements 
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DATA REPRESENTATION 


Numbers 

The decimal digits 0 through 9 and the decimal point are used in the 
usual way. The character ", called the negative sign, is used to denote 
negative numbers. It appears as the leftmost character in the 
representation of any number whose value is less than zero: 


The negative sign, , is distinct from - (the symbol used to denote 
subtraction) and can be used only as part of the numeric constant. 


Scaled Representation (Scientific Notation) 

You can represent numbers by stating a value in some convenient 
range, then multiplying it by the appropriate power of 10. This type of 
notation is called scaled representation in APL. The form of a scaled 
number is a number (multiplier) followed by E and then an integer (the 
scale) representing the appropriate power of 10. For example: 


Number 

Scaled Form 



t 

—Multiplier 

66700 

6.67 E4 



4 _ 

— Scale 

.00284 

2.84E3 



The E (E can be read times 10 to the) in the middle indicates that this 
is scaled form; the digits to the right of the E indicate the number of 
places that the decimal point must be shifted. There can be no spaces 
between the E and the numbers on either side of it. 


Numeric Value Range 

Numeric values in the 5110 can range from "7.237005577332262E75 
to 7.237005577332262E75. The smallest numeric value the 5110 can 
use is ±5.397604346934028E "79. 


Numeric Value Precision 

Numbers in the 5110 are carried internally with a precision of 16 
significant digits. 



Character Constants 


Zero or more characters enclosed in single quotes, including 
overstruck characters and blank characters (spaces), is a character 
constant. The quotes indicate that the characters keyed do not 
represent numbers, variable names, or functions, but represent only 
themselves. When character constants are displayed, the enclosing 
quotes are not shown: 

*ABCDEFG' 

ABC HE F (3 

' .1.23ABC ‘ 

123ABC 

Mf'THE ANSWER IS: * 

M 

THE ANSWER IS: 

When a quote is required within the character constant, a pair of 
quotes must be entered to produce the single quote in the character 
constant. For example: 

1 BON' 'T GIVE THE ANSWER AWAY’ 

DON'T GIVE THE ANSWER AWAY 


Logical Data 

Logical (Boolean) data consists of only ones and zeros. The relational 
function (> £ - < £ *) generate logical data as their result; the result 
is 1 if the condition was true and 0 if the condition was false. The 
output can then be used as arguments to the logical functions 
( A v ” a v ) to check for certain conditions being true or false. 
Logical data can also be used with the arithmetic functions, in which 
case it is treated as numeric 1 's and 0's. 
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ARRAYS 


Array is the general term for a collection of data, and includes scalars 
(single data items), vectors (strings of data), matrices (tables of data), 
and arrays of higher dimensions (multiple tables). All primitive (built-in) 
functions are designed to handle arrays. Some functions are designed 
specifically to handle arrays rather than scalars. Indexing, for example, 
can select certain elements from an array for processing. 

One of the simplest kinds of arrays, the vector, has only one 
dimension; it can be thought of as a collection of elements arranged 
along a horizontal line. The numbers that indicate the positions of 
elements in an array are called indices. An element can be selected 
from a vector by a single index because a vector has only one 
dimension. The following example shows assigning a numeric and a 
character vector to two variable names, N and C; the names are then 
entered to display the values they represent: 

M<5 6.2 ~3 888 95.12 
N 

5 6.2 “3 888 95.12 
O'ABCDEFG 1 
C 

ABCDEFG 
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Generating Arrays 

The most common way to generate an array is to specify the shape 
the array is to have (that is, the length of each coordinate) and the 
values of the elements of the new array. The APL function that forms 
an array is the reshape function. The symbol for the reshape function 
is p. The format of the function used to generate an array is XpY, 
where X is the shape of the array and Y represents the values for the 
elements of the array. For the left argument (X), you enter a number 
for each coordinate to be generated; this number indicates the length 
of the coordinate. Each number in the left argument must be 
separated by at least one blank. The values of the elements of the 
new array are whatever you enter as the right argument (Y). The 
instruction 7pA means that the array to be generated has one 
dimension (is a vector) seven elements in length, and that seven 
values are to be supplied from whatever values are found stored under 
the name A. It does not matter how many elements A has, as long as 
it has at least one element. If A has fewer than seven elements, its 
elements are repeated as often as needed to provide seven entries in 
the new vector. If A has more than seven elements, the first seven 
are used. The following examples show generation of some vectors: 



7 Pi 

A»« 

3 

*:> 

A.. 

3 :l 2 

3 

1 


2 pi 2 

:3 


y. 

123 




5pl . 

3 


, 3 

1 .3 .1.. 

3 

1 
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An array with two coordinates (rows and columns) is called a matrix. 


Columns 



55 6 7 8 - Rows 

9 10 11 12 , 


To generate a matrix, you specify X (left argument) as two numbers, 
which are the lengths of the two coordinates. The first number in X is 
the length of the first coordinate, or number of rows, and the second 
number is the length of the second coordinate, or number of columns. 
The following example shows how a matrix is generated: 

M<-2 3pl 2 3 4* 5 6 
M 

1 2 3 
4- 5 6 

M<-2 4-P ‘ ABCDEFGH ‘ 

M 

A BCD 
EFGH 

m<-2 3pM 
Ml 

ABC 

BEF 


Note that the values in the right argument are arranged in row order in 
the arrays. If the right argument has more than one row, the elements 
are taken from the right argument in row order. 
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The rank of an array is the number of coordinates it has, or the 
number of indices required to locate any element within that array. 
Scalars are rank 0. Vectors have a rank of 1, matrices have a rank of 
2, and N-rank arrays have a rank from 3 to 63 (where N is equal to the 
rank). N-rank arrays, like matrices, are generated by providing as the 
left argument a number indicating the length for each coordinate (for 
example, planes, rows, and columns). The following examples show 
how to generate 3-rank arrays. Note that the elements taken from the 
right argument are arranged in row order: 


A BCD 
EFGH 
IJKL 


A<- ‘ ABCDEFGHIJKLMN0PQRSTUVUXYZ ‘ 

2 3 ‘ipA 

\ 

'- 2-Plane, 3-Row, 4-Column Array 


MN'GP 

QRST 

UVWX 

AB 

CD 

EF 



GH 

IJ 

KL 


4-Plane, 3-Row, 2-Column Array 


MN 

OP 

QR 

ST 

UV 

WX 
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Finding the Shape and Rank of An Array 


Once you have generated an array, you can find its shape (number of 
elements in each coordinate) by specifying p (shape function) with 
only a right argument, which is the name of the array. If A is a vector 
with six elements and you enter pA, the result is one number because 
A is a one-dimensional array. The number is 6, the length (number of 
elements) of A. The result of the shape function is always a vector: 

A*-:l.l 1 222 333 *+'+»+ 555 666 
pA 

6 

The shape of a matrix or N-rank array is found the same way: 

ii<-2 3 p 1 2 3 4 3 6 
M 

:l. 2 3 
4- 3 6 

pH 

2 3 

Ri -2 3 4-pi 2 3 4 5 6 7 8 
R 

,'t 2 3 4 
5 6 7 8 
1 2 3 4 

5 6 7 8 
1 2 3 4 
3 6 7 8 
pR 

2 3 4 


In some cases, it might be necessary to know just the rank, the 
number or coordinates (or indices) of an array. To find the rank, enter 
p p (shape of the shape) and a right argument, which is the name of 
the array: 

AM 11 222 333 4-4-4 355 666 
B<-2 3 p :L 2 3 4 5 6 
02 3 4pi 2 3 4 5 6 7 
pA 

6 

PPA 

1 

pB 

2 3 


PC 

2 3 4 

PPC 

3 
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The following table shows what the shapes and ranks are for the 
various types of arrays: 


Data 

Type 

Shape pX 

Rank ppX 

Scalar 

No dimension (indicated 
by an empty vector). 

0 

Vector 

Number of elements. 

1 

Matrix 

Number of rows and the 
number of columns. 

2 

N-rank 

arrays 

Each number is the length 
of a coordinate. 

N 

Empty Arrays 




Although most arrays have one or more elements, arrays with no 
elements also exist. An array with no elements is called an empty 
array. Empty arrays are useful when you are creating lists (see 
Catenation in this chapter) or branching in a user-defined function. 

Following are some ways to generate empty arrays: 

• Assign lOto a variable name to generate an empty vector: 


EVECTOR*x 0 
EVECTOR 


pEVECTOR 

0 

\ _ 


An empty array is indicated 
by a blank display. 

The shape of the empty vector 
is zero (zero elements). 




Use a zero length coordinate when generating a multidimensional 
array: 


3 0 


EMATRIXl«-3 0p\() 
EMATRIXl 


pEMATRIXl 


This matrix has three rows and no (0) 
columns. If one of the coordinates is 
not zero, you cannot generate the 
empty array. 

A Blank Output Display 


• A function might generate an empty vector as its result; for 
example, finding the shape of a scalar: 

P ’ A' 

-*---A Blank Output display. 
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INDEXING ARRAYS 


You may not want to refer to the whole array but just to certain 
elements. Referring to only certain elements is called indexing. Index 
numbers must be integers; they are enclosed in brackets and written 
after the name of the variable to which they apply. Assume that A is 
assigned a vector as follows: A 11 121314151617. The result of 
entering A is the whole vector, and the result of entering A[2] is 12 
(assuming the index origin is 1). 

Here are some more examples of indexing: 


A Ml 1.2 13 14- 15 16 17 
AC 3 3 
13 

AC5 3 7 III 
15 13 17 11 

B -" 3 1 l+ 6 Blank Character 

AC EG 

13 11 14- 16 

B<-' ABCDEFGHI,JKLMNOPQRSTUVWXYZ ' 

BC 4 1 14 27 1 14 4 27 3 12 1 9 183 
DAN AMD CLAIR 

022 9 18 7 9 14 9 1 
BCC3 

VIRGINIA 


If you use an index that refers to an element that does not exist in the 
array, the instruction cannot be executed and INDEX ERROR results: 


A 

11 12 13 14 15 16 17 
AC83 

INDEX ERROR 
AC 83 


You cannot index or do anything else with an array until after the array 
has been specified. For example, suppose that no value has been 
assigned to the name Z; then an attempt to store values in certain 
elements within Z would result in an error, because those elements do 
not exist: 

Z C 3 4 3 <-18 46 
VALUE ERROR 

ZC3 4 3*- 18 46 


A 





Indices (whatever is inside the brackets) can be expressions, provided 
that when those expressions are finally evaluated, the results are 
values that represent valid indices for the array: 


B 

ABCDEFGH 1 JKLMNOPQRSTUVUXYZ 
XM 2 3 4 5 
BCXx23 

BDFHJ 

X 

1 2 3 4 5 

b i:: i + x 3 ::i 

DGJMP 

The array from which elements are selected does not have to be a 
variable. For example, a vector can be indexed as follows: 


2 3 5 7 9 11 13 15 17 19C7 2 4 23 
13 3 7 3 

' ABCDEFGH I JK LMNO PQ RSTUVWXYZ ' I” 12 15 15 11 27 16 13 
LOOK PA 

’ABCDEFGHIJK LMNOPQ RSTUVWXYZ * C2 4#>4 15 14 27 13 1 IB 25 

DON 

MARY 


Indexing a matrix or N-rank array requires an index number for each 
coordinate. The index numbers for each coordinate are separated by 
semicolons. Suppose M is a 3 by 4 matrix of consecutive integers: 

M<-3 4p \ 12 

If you ask to see the values of M, they are displayed in the usual 
matrix form: 

M 

12 3 4 

5 6 7 8 

9 10 11 12 

If you want to refer to the element in row 2, column 3, you enter: 

M I" 2; 3 3 
7 

If you want to refer to the third and fourth elements in that row, you 
enter: 


Mr.2; 3 43 

7 8 
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Similarly, to refer to the elements in column 4, rows 1, 2, and 1, you 
enter: 

Mill 2 :i.; m:i 

4 8 4 

You can use the same procedure to select a matrix within a matrix. If 
you want the matrix of those elements in rows 2 and 3 and columns 1, 
2, and 1 of M, you enter: 

hi :2 3; :i. 2 1:1 

5 6 5 

9 10 9 

If you do not specify the index number for one or more of the 
coordinates of the array that you are indexing, APL assumes that you 
want the entire coordinate(s). For instance, to get all of row 2, you 
enter: 

mi: 2; ::i 
5 6 7 8 

Or to get all of columns 4 and 1, you enter: 

MU'I- 11 

4 1 

8 3 

.1.2 9 

Note: You still have to enter the semicolon to make clear which 
coordinate is which. The number of semicolons required is the rank of 
the array minus one. If the correct number of semicolons is not 
specified, RANK ERROR results: 

M«~3 4 p \ 1.2 

PH 

3 4 

mi::6::k-9 
RANK ERROR 

MC63<-9 

A 

You can change elements within an array by assigning new values for 
the indexed elements. (The rest of the array remains unchanged.) 

A«-3 3 p 1. 2 3 4 3 6 7 8 9 
A 

1. 2 3 

4 5 6 
7 8 9 

AC2;2 3 ::i :i. o 20 

A 

1 2 3 

4 1.0 20 
7 8 9 
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JOINING ARRAYS TOGETHER 


You can join two arrays to make a single array by using the catenation 
or lamination functions. The symbol for these functions is the comma. 

Catenation 

When catenating vectors, or scalars and vectors, the variables are 
joined in the order in which they are specified. For example: 

A «-l 2 3 4 
B «-4 5 6 
A, B 

1 2 3 4 4 5 6 

B # A 

4 5 6 1 2 3 4 

A, 2 

1. 2 3 4 2 

3 i A 

3 1 2 3 4 

When catenating two matrices or N-rank arrays, the function can take 
the form A,[I]B, where I defines the coordinate that will be expanded 
when A and B are joined. If the coordinate is not specified, the last 
coordinate is used. When A and B are matrices and [I] is [1], the first 
coordinate (number of rows) is expanded; when [I] is [2], the last 
coordinate (number of columns) is expanded. The following examples 
show how to catenate matrices: 

Graphic Representation 

A B 

A 2 3 p .1.0 20 30 40 50 6 0 
B<-2 3pU 22 33 44 55 66 


A, B 

10 20 30 11 22 33 
40 50 60 44 55 66 

a , i" 2 :i b 

10 20 30 11 22 33 
40 50 60 44 55 66 

a , r. 

10 20 30 
40 50 60 

11 22 33 
44 55 66 
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Arrays of unequal sizes can be catenated, provided that the lengths of 
the coordinates not specified are the same (see the first example 
following). If the coordinates not specified have different values, an 
error results (see the second example following): 


Bi-2 4 #>11 22 33 44 55 66 77 88 


A<-2 3(010 20 30 40 50 60 


10 

20 

30 

40 

50 

60 


11 

22 

33 

44 

55 

66 

77 

88 


A, I" 23B 

10 20 30 11 22 33 44 
40 50 60 55 66 77 88 


A_ B 


10 

20 

30 

11 

22 

33 

44 

40 

50 

60 

55 

66 

77 

88 



A 

10 

20 

30 


a 11:: i :jb 

F N G T H F R R 0 R -«- 


40 

50 

60 


A, i: 1 3 B 

B 

11 

22 

33 

44 

A 


55 

66 

77 

88 


A scalar can also be catenated to an array. In the following example, a 
scalar is catenated to a matrix. Notice that the scalar is repeated to 
complete the coordinate: 


A*-2 3f> 10 
A 


10 

20 

30 


4 0 

50 

60 



A, C2 

.199 

10 

20 

30 

99 

40 

50 

60 

99 



A, C1 

399 

10 

20 

30 


40 

50 

60 


99 

99 

99 



20 30 40 50 60 


A vector can also be catenated to another array, provided the length 
of the vector matches the length of the coordinate not specified. See 
the following examples: 


10 20 30 99 
40 50 60 88 


8 

10 

20 

30 

99 


40 

50 

60 

88 


A,Cl399 88 

LENGTH ERROR - 

A, i: 13 99 88 


10 

20 

30 

40 

50 

60 

99 

88 









The catenate function is useful when you are creating lists of 
information. Sometimes it is necessary to use an empty array to start 
a list. For example, suppose you want to create a matrix named 
PHONE where each row will represent a seven-digit telephone number. 
First you want to establish the matrix, then add the telephone numbers 
at a later time. The following instruction will establish an empty array 
named PHONE with no (0) rows and seven columns: 


0 7 


PHONE M) 7p x 0 
PHONE 


P PHONE 


Blank display indicates an 
empty array. 


Now, the telephone numbers can be added as follows: 


PHONEDPHONE 
PHONE 
5336686 

PHONE H :> HONE 
PHONE 


5336686 
M-56M 771 

P PHONE 



, \: 1 ::i • 5336686 ■ 
, Cl3 • 1+564771 * 


The list of telephone numbers 
now contains two rows. 
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Lamination 


When laminating two variables together, the function joins the 
variables together by creating a new coordinate. The function takes 
the form A,[I]B, where I is an index number that must be a fraction. 
This index number specifies where the new coordinate is added. If the 
index number is less than 1, the new coordinate is added before the 
first coordinate; if the index number is between 1 and 2, the new 
coordinate is added between the first and second coordinate; and so 
on. For example: 


AAA 

AAA 

AAA 


BBB 

BBB 

BBB 


A<-3 3 p ‘ A ' 
A 


B<-3 3 p ' B ' 
B 


Graphic Representation 



AAA 

AAA 

AAA 

BBB 

BBB 

BBB 

2 3 3 


OA, L , i::ib 
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AAA 

BBB 


oa, \: i , i::ib 

c 


AAA 

BBB 


AAA 

BBB 

3 2 3 


1A1 A1A 


lAlAlA ? 


A 

A 

Aj 

B_ 

B 

B - 


The new coordinate is added between the 
first and second coordinate. 


oa, 1:2. :i. ::i b 

c 

AB 

AB 

AB 

AB 

AB 

AB 

AB 

AB 

AB 

PC 

•X -x 

V*. A*> mmm ^ mm _____ 


IaTbI 


A 

B 

A 

B 

A 

B 


The new coordinate is added after the 
second coordinate. 
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The new coordinate is always 2 because two variables are joined 
along a new coordinate. 


Unless one of the variables is a scalar, arrays of unequal sizes cannot 
be laminated together. For example: 


AK5 Zp\ 9 
A 

1 2 3 
4 5 6 
7 8 9 

OA, I! . 1310 
C 

1 2 3 

4 5 6 

7 8 9 


liolioh 


1 

2 

4 

5 

7 

8 


10 

10 

10 


10 

10 

10 


10 

10 

10 



B«-2 

Vl 

Zpl 

10 

11 

Jk." 

12 


13 

14 

15 




b , i::. 

, 13A 

.EMC 

3TH 

ERROR 


B, i: 0.13 A 


13 14 15 



OjoloL 





USEFUL APL STATEMENTS AND USER-DEFINED FUNCTIONS 


To remove duplicate blanks from a character vector: 


VG0MPRESSCD3V 

V Z*COMPRESS U; I 

Cl3 Z*1 MilQDXIiV-*' * >/W<-* ‘ ,W 

V / 


COMPRESS 'AAA / BBBB CCC DDD' 

AAA BBBB CCC DDD / 


The right argument is the character vector. 


To create a matrix from a character vector with a delimiter for each 
row: 

VF0RMnT.1V ^DIO will’ be set to 0 just during 

V M*D FORM S;A;B;XjZ;DIO^ the execution of this function. 

C13 010*0 

C23 M*(X*S^D)/S*,S 

131 Z*<X*14X,*~ltX>/l+\pX 

CM-3 M«-< <pA> ,B>p< , (A™:l.) <> , > \B*0rr/A*XCZ-13/Z“0 / ":UZ)\M 

V 

•o' FORM • A»B‘>CCC»D* 

A 

B 

qqq In this example, the » character is used 

l\ as the delimiter. The left argument specifies 

the delimiter, and the right argument 
specifies the character vector. 
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To remove the alphabetic characters from a character vector, leaving 
only the numeric characters and blanks: 

VREMOVECO3V 

V NEW*-REMOVE OLD 

C t 3 NEW* < OLD*- ' 0123456789 . * > /OLD 

V 

OLD*-' DAN 30 DAVE 29,5 JERRY 37 MEL 40 , 0 ’ 
REMOVE OLD 
30 29,5 37 40.8 

To replace all trailing blanks with a minus sign: 

VBLANKSCCPV 

V Z*-BLANKS MJV 

c :l ::i v*- j <pa\(dm™‘ * 

I1’23 Z *-, M 

1:33 zi::v/w>v 3 *-' 

1:43 z*- < pM) pz 

v 


MAT*-2 5p*AB CDE * 

MAT 

AB 

GDI- 

BLANK S MAT 

AB. 

CDE--- 

Return all elements of a vector that are even numbers: 

VEVENCQ3V 

V Z*EVEN V 

Cl 3 Z*-< 0 ss 2 I V)/V 

V 


EVEN 0 1 2 3 4 5 6 7 8 9 
0 2 4 6 8 

To delete all comment lines from a user-defined function: 


VCOMMENTCCI3V 

V COMMENT FN;M 

I! 13 M*-0FX< ME ; 13/ ' rt ' ) /M+QCR FN 

V 


VADD 

Cl 3 ft COMMENT LINE .1. 
i:23 3+4 

I! 3 3 a COMMENT LINE 2 
r.43 V 


COMMENT 'ADD * 
VADDC03V 

V ADD 

Cl 3 3+4 

V 
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To merge two variables with the same shape into a single vector: 


EMERGE II rP’w' 

V Z*A MERGE B 

i::i.::i z<-,A,roio-o.sa b 

y 

A<-2 2p'A’ 

B*-2 2p ' B * 

A MERGE B 
AAAABBBB 

To delete duplicate elements in a vector: 

vdupu:catei::i"pv 

V Z<-DU PLICATE V 

1:1:1 z<“( < xpv>~v\v>/v<~, v 

v 


DUPLICATE 1 2 3 3 M- 2 5 6 5 5 
1 2 3 '+ 5 6 


To find the first nonblank character in a character vector: 

VNQNBLANKCmV 

V Z^NQNBLANK W 

111 Z«11 <* * >/W 

V 


' DAN 1 


NONBLANK V 
D 


VNONBLANKXCCPV 
V Z<-NONBLANKX W 
II1 :j Z«-<<W ’ )/W 
y 


NONBLANKX V 
D 
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To determine whether a variable is character or numeric: 


VDETERMINEEI33V 
V DETERMINE U 

i: i ::i * nc * i::oio+ <" 1 1 2 1 1 1, w)«* * ::i 

v 


c 

N 


N 


A<- ’ 9' 

B*-9 

DETERMINE A 
DETERMINE B 


The result is C for character or 
N for numeric. 


vdetermineiccpv 

V DETERMINE! W 

1 NC IIOIO * ‘ *=1 tO pUIl 

V 

DETERMINE! A 


DETERMINE! B 


To make scalar or vector into a matrix: 

9MATRIXCQ3V 

V ^MATRIX M 

Cl 3 Z<-( ™2t1 , 1, pM>pM 

V 


A<- ’ ABCDEF6 ‘ 
X<- MATRIX A 
X 

ABCDEFG ^_ 

pX 

1 7 


The result is a 1 by 7 matrix. 


To delete all user-defined function names starting with a specified 
character vector from the active workspace: 

VDELETEFN I" |139 

V DELETEFN C;NLjZ;X 

1 13 Z<-< < < < 11 pNL) , pC ) t NL ) a , =Cf , C)/NL<- < 11C) ONL 3 

C23 Xf-OEX Z 

V 


1 13 


v 

v 


vaddi::i::i::iv 

add 

3-Hl- 


A user-defined function in the 
active workspace 


VALUE 


DELETEFN 
ADD 
ERROR 
ADD 


AD 


The function is no longer in the 
active workspace 





To count the number of occurrences of each unique character in a 
character vector: 


VCOUNTC03V 
V Z*-COUNT W; (JC 

r i i z<-+/u». = < hav€ w > /riAv 
v 


COUNT 'ABBCCCDDDDE 1 
:l. 2 3 '+ :L 

COUNT *ABCDBCDCDD* 

:t 2 3 4- 


To center the character string in each row of a character matrix: 

VCENTERCmV 
? Zf-CENTER M 

i:: 1 :i z<- < - r < */a\<i>m~ 1 1 ) *2 > < •♦•/a\m~ ■ • > m 

v 


MAT*-3 6p' A B C 

MAT 
A 
B 

C 

CENTER MAT 
A 
B 
C 


To right-justify the character string in each row of a character matrix: 

VRIGHTJUSTIFYCH3V 

V Z< -RIGHT JUSTIFY M 

I'.! 1.1 Z(•••• + /a \ ((|>M)' * XDM 

V 


MAT 

A 

B 

C 


RIGHTJUSTIFY MAT 
A 
B 
C 
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To left-justify the character string in each row of a character matrix: 


VLEFTJUSTIFYCCPV 

V ZH-EFTJUSTIFY M 

Cl 3 Z<~(+/a\M~. ‘ * ><I>H 

V 


HAT 

A 

B 

C 

LEFTJUSTIFY HAT 
A 
B 
C 


To list each user-defined function in the active workspace: 


VLISTFNSITPV 

V LISTFNS;ALF;NAHE;I;FUN;COL;NO;010;0PU 

r:;l.:i a THIS FUNCTION lists all functions in THE active workspace 
c: 2 ::i aexce pt listfns and l istvars . 

1 : 3:1 UKX-1 
1 :: 11 :i 0PWH.32 
1 : 5:1 NAHEH3NL 3 

1 : 6:1 ALF<-' ABCDEFGHIJKLMNOPQRSTUVUXYZ * 

C73 ALFALF, ’ AABCDEFGHIJKLMNOPQRSTIJVWXYZA 1 

C83 ALFALF, ‘ 0l23M'567S9 r . 

C93 NAME<-NAHEC&66. 1 .ALFxNNAHEJ 3 

CIO 3 :i>o 

1 :i 1 :i LOOP:-><<ItpNAHE)<I*• I+1)/0 
C 123 ■* < a/NAMEC I; 3 = < “ 11 pNAHE ) t * LISTENS ‘ > /LOOP 

i:i3:.l -»<a/NAHECIJ 3«<"ltpNAHE)t 'LISTVARS' )/LOOP 
i: 1 1 + 3 NO<-11 pFlJNf-OCR NAHECIJ 3 

I.! 15 3 COL<- < ( NO, 1) p ‘ i:' ) , < t ( NO , 1) p “ 1. + x NO ) , ( ( NO , 2) p *3 ‘ ) 

i: 163 COLC1J 3<-(“It pCOL) t ' * 

i:i7:i COL, FUN 

C183 2 Ip* ' 

i:i9:i -H...OOP 

V 


LISTENS 
BLANKS H; V 
I!! 13 V*- , (|>a\<|)H~-' 1 

i: 23 Z <-, H 
I!! 33 ZCV / x pV3+* * - ' 
C >F1 Z<-(pH)p Z 


Z*A BY B;ROU 
i: 13 A<-(2t ( pA) j 1 1) pA 

LIS T F N S C18 3 -- 


The ATTN key was pressed before 
all the functions in the active 
workspace were listed. 







To list each variable and associated value in the active workspace: 


VLISTVARSCI33V 

V LISTVARS;ALF;VAR;X;RJ HX0 

Cl3 a THIS FUNCTION LIST THE VARAIBLES IN THE ACTIVE WORKSPACE 

1 : 2:1 OXOf-X 

1 : 3:3 RH t (:>VAR<"i;]NL 2 

C43 ALF«- ‘ ABCDEFGHX JKLMNOPQRSTUVUXYZA ' 

C53 ALF«-ALF , ' ABCDEFGHX JKLMNOPQRSTUVUXYZA ' 

C63 ALF«-ALF, * 0X23456789 v .... 

C73 VAR *■ VARC 6661 ALF\NVAR; :i 

1:8:1 1*0 

1:9:1 LOOP:-><R-.:i:<-x- 4 -x)/o 

Cl03 2 X #>* • 

ci 13 id* 1 ' ..vari:x; :i 

CX23 -H...00 P 

V 

LXSTVARS 


A 

10 20 30 
40 50 60 


B 

I 1 99 "K "K 

44 55 66 


AAA 

B 



The ATTN key was pressed before 
all the variables in the active 
workspace were listed. 


LI ST VARS C12:i 


To field-protect high-order digits: 


v p rote: n :iv 

V Z<~N PROT V 

1 : X 3 Z< - ( " N) t ( < N-3) p ' • ) , V 

V 


X0 PROT ■123.45* 
**#* 123.45 


APL Language Elements 37 







To delete leading blanks from a character string: 


7DLBCI337 
7 ZHJLB A 

Cl3 Z^-<’“1 + <A=* ' ) \ 0 ) 4 A 

7 

DLB ' 123.45’ 

123.45 

To join vectors and print results as a single, sorted vector: 

7JOINCH37 
V Z*A JOIN BjT 
ci3 z<-t b:i 
7 

AMO 5 6 2 3 1 

BM.5 5 2 2 7 

A JOIN B 

1 2 2 2 3 5 5 6 7 10 15 

7J0IN1C037 
7 Z*A JOINI B;T 
Cl 3 Z<-TC7T«-A,B3 

7 


A JOINI B 

15 10 7 6 5 5 3 2 2 2 1 




To sort up to the first nine columns of a matrix with each row 
representing a name: 



vsort r: o ::i v 

v Z«-SORT LI ST ; ALF 

A I... F ' A B C D E F G HIJ K L M N 0 P Q R S T U 
Z <-• L1 8 T l A 2 9 1A L F « A LIS T ; 2 
v 


L *• 6 7 p ' J E N N Y J A N L. U 0 Y A R 0 HIE D 0 U G L A S B F T PI 

L 

JENNY 

JAN 

LUCY 

ARCHIE 

DOUGLAS 

BETH 

I.J-80RT L 


ARCHIE 

BETH 

DOUGLAS 

JAN 

JENNY 

LUCY 


To find the location of a name in a list of names: 

7findi::o:iv 

V ZH..I8T FIND NAME 

I!! 1 2 2. ( ( L18 T a , = ( -1.1 p L18 T ) f N A M E ) ) / \ 11 p L18 T 

V 

L FIND ’JAN’ 

•+ 


To delete a name from a list of names: 

VDELCrPV 

V Z<-LIST DEL NAME 

C1 2 7.A- < (~L I ST a :l. t pL I ST) f NAME) ) /L 1ST 

7 

L DEL * JAN* 

ARCHIE 

BETH 

DOUGLAS 

JENNY 

LUCY 
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To perform a specified operation if a condition is true 


VIFCrPV 

V ZK)P IF CONO 
m Zf-COND/OP 

V 

I *-3 

■PRINT' IF 1=3 


IF 1=4- 


PRINT 


• print ‘ 



Chapter 4. Active Workspace Control 


The active workspace is the internal storage where calculations are 
performed; it is also the place where variables and user-defined 
functions are stored. The 5110 system commands, system functions, 
and system variables are used to control the active workspace. In this 
chapter, the following topics are discussed: 

• The active workspace environment in a CLEAR WS 

• Getting information about the active workspace 

• Changing the active workspace environment 

• Getting data into the active workspace 

• Active workspace storage considerations 
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THE ACTIVE WORKSPACE ENVIRONMENT IN A CLEAR WS 


When the 5110 is first turned on, or the RESTART switch is pressed, 
or the )CLEAR command is executed, the active workspace 
environment has the following characteristics: 

« The index origin (DIO) is 1. 

« The comparison tolerance (OCT) is IE-13. 

« The random number seed {(URL) is 16807. 

• The print width (DPW) is 64. 

• The print precision (DPP) is 5. 

• The latent expression (DLX) is an empty vector. 

« The workspace identification [ )WSID ] is CLEAR WS. 

• The number of symbols allowed [ )SYMBOLS ] is 125. 

(See the IBM 5110 APL Reference Manual, SA21-9303, for a complete 
description of the system variables and system commands.) 

These characteristics control the way some of the APL functions and 
system commands will work in the active workspace. For example, if 
you have assigned 125 variable names and you enter the statement: 

NAME 1.26*- * ROCHESTER ‘ 

SYMBOL TABLE FULL 

NAME126 

A 

a SYMBOL TABLE FULL error message is displayed, because only 125 
symbols (names) are initially allowed in the active workspace. How 
you change some of the active workspace environmental 
characteristics is discussed next. 




CHANGING THE ACTIVE WORKSPACE ENVIRONMENT 


You can change the system variables, workspace identification 
[ )WSID ], and number of symbols allowed [ )SYMBOLS ]. For the 
system variables, you simply assign them a new value. For example: 


OIOM)-*-The index origin is now 0 

The number of symbols allowed in the active workspace can be 
established only in clear workspace. That is, the size of the symbol 
table must be established by the 5110 before any other data is placed 
in the active workspace. 


Symbol Table. Eight bytes of active 
workspace storage are reserved for 
each symbol allowed. 


Active Workspace 

The number of symbols allowed is initially set to 125, which requires 
1000 bytes of active workspace storage. 

There might be times when you have used the maximum number of 
symbols allowed, so you may need to increase the maximum number 
of symbols allowed. If you change the number of symbols allowed in 
a clear workspace and then use the )LOAD command to load a stored 
workspace into the active workspace, the number of symbols allowed 
is the same as when the stored workspace was written to the media. 
However, you can use the following procedure to change the number 
of symbols allowed: 

1. Save the contents of the active workspace using the )SAVE 
command. 

2. Clear the active workspace using the )CLEAR command. 

3. Set the new number of symbols allowed using the )SYMBOLS 
command. For example: 

) SYMBOLS 251.-* -Now, 251 symbols are allowed. 

WAS 12 !5 
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4. Copy the stored workspace into the active workspace using the 
)COPY command. Using the )COPY command does not affect the 
number of symbols allowed in the active workspace. The )COPY 
command is discussed later in this chapter. 

The workspace identification specifies the device/file number and file 
ID where the contents of the active workspace are stored when a 
)SAVE or )CONTINUE command is issued. The )WSID command can 
be used to change the device/file number and file ID where the 
contents of the active workspace is to be stored. For example: 


This device file number and file ID is now 
associated with the active workspace. 


Change the workspace identification. 


Now, when the )SAVE [or )CONTINUE] 
command is issued, the contents of the 
active workspace are written to the new file. 


)LOAD 11001. DATA 
LOADED d 10 0 :l^ DATA, 


)USID 12001 TEST 
UAS 11001 DATA 
) SAVE 

SAVED 12001 TEST 



GETTING DATA INTO THE ACTIVE WORKSPACE 

You can get data into the active workspace by entering the data from 
the keyboard or reading the data from a tape or diskette file. You read 
data from a tape or diskette file using an APL shared variable or one 
of the following system commands: 

• )LOAD 

• )RESUME 

• )COPY 

• )PCOPY 

• )PROC 

See Chapter 10, Input/Output Control, for information on reading data 
using APL shared variables. The system commands used for reading 
data into the active workspace are discussed next. 



The )LOAD and )RESUME Commands 

The )LOAD and )RESUME commands are used to load an entire stored 

workspace into the active workspace. The contents of the stored 

workspace then replace the contents of the active workspace. The 

)LOAD command has the following characteristics: 

• Loads any stored workspace, which was written to tape or diskette 
by the )SAVE or )CONTINUE command, into the active workspace. 

• If the stored workspace has a latent expression assigned to the DLX 
system variable, the latent expression is executed each time the 
)LOAD command is used to load that stored workspace into the 
active workspace. 

• If the stored workspace has shared variables established, the shared 
variables are not reestablished when the )LOAD command loads the 
stored workspace into the active workspace. 

The )RESUME command has the following characteristics: 

• Loads any stored workspace which was written to tape or diskette 
by the )SAVE or )CONTINUE command into the active workspace. 

• If the stored workspace has a latent expression, the latent 
expression is not executed when the continued (stored) workspace 
is loaded into the active workspace. 

• The primary reason for using this command is to reestablish the 
system environment as it was when the workspace was written to 
the media. That is, if the stored workspace was written to the 
media by the )CONTINUE command, any shared variables and/or 
suspended functions in the stored workspace are reestablished in 
the active workspace by the )RESUME command. See The 
)RESUME Command in the IBM 5110 APL Reference Manual, 
SA21-9303, for a description of how shared variables are 
reestablished. 
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The )COPY and )PCOPY Commands 


The )COPY and )PCOPY commands are used to copy all or selected 
objects (variables or user-defined functions) from a stored workspace 
into the active workspace. When these commands are used, the 
objects are copied into the active workspace without replacing the 
entire contents of the active workspace. When the )COPY command is 
used, any objects already in the active workspace are replaced by the 
objects specified by the )COPY command if the objects have the same 
name. When the )PCOPY command is used, any objects in the active 
workspace are protected and not replaced by the specified objects if 
the objects have the same name. These commands have the 
following characteristics: 

• These commands can only be used to copy objects from a 
workspace written to tape or diskette by the }SAVE command. If 
you want to copy objects from a workspace written to tape or 
diskette by the )CONTINUE command, the stored workspace must 
be loaded into the active workspace and then written to the media 
by the )SAVE command. 

• These commands cannot be used if the active workspace contains 
suspended functions. 

• These commands can be used to copy objects from several stored 
workspaces into the active workspace. 


The IPROC Command 

An alternative to entering data from the keyboard is to get the data 
from a procedure file. A procedure file contains character records that 
represent any input that is possible from the keyboard, such as system 
commands, function definition, and APL expressions. When the )PROC 
command is issued, the 5110 reads and executes one procedure file 
record at a time until the last record (end-of-data) is processed. Then 
the 5110 goes back to using regular keyboard input. [See the IBM 
5110 APL Reference Manual, SA21-9303, for a complete description of 
procedure files and the )PROC command.] 

A procedure file must be a type I or U data file and the records cannot 
be greater than 128 characters. (See Chapter 10, Input/Output 
Control, for a complete description of data files.) 



A procedure file is useful for doing unattended applications that 
require using system commands and/or function definition. For 
example, assume you have an application that requires several 
user-defined functions. However, not enough workspace storage is 
available to contain all of the user-defined functions. In this case, you 
might: 

1. Use the )SAVE command to store the user-defined functions on 
tape or diskette. 

2. Create a procedure file that contains the following character 
records: 

a. A )COPY command to copy the first user-defined function(s) 
required for the application into the active workspace 

b. The statement(s) required to execute the user-defined 
function(s) 

c. An )ERASE command that erases user-defined functions and 
variables that are no longer required 

d. A )COPY command that copies the next user-defined 
function(s) required for the application into the active 
workspace 

The previous steps are repeated until the application is complete. 

3. Use the )PROC command to execute the statements from the 
procedure file. After the last statement is read and executed, the 
5110 again accepts input from the keyboard. 

Note: Using the )PROC command requires approximately 800 
bytes of active workspace storage. The active workspace is 
always cleared the first time a )PROC command is used after you 
turn the power on or press RESTART, because the required 800 
bytes can be allocated only in a CLEAR WS. The active 
workspace is not cleared for any subsequent )PROC commands 
because the 800 bytes are already allocated until the power is 
turned off or RESTART is pressed. Therefore, if you have any 
useful data in the active workspace, you should save this data 
before using the )PROC command the first time. 
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INFORMATION PROVIDED ABOUT THE ACTIVE WORKSPACE 


You can get information about the active workspace by simply 
entering certain system commands, system variables, or system 
functions without specifying any parameters or arguments. The 
system commands that provide information about the active 
workspace are: 


System Command Information Provided 


)SYMBOLS 


)WSID 


)FNS 

)VARS 

)SI 


)SINL 


How many symbols are allowed 
and how many symbols are 
currently being used. (The symbols 
consist of labels, variable names, 
user-defined function names, and 
any system variables and functions 
that have been used.) 


The current workspace ID and 
device/file number. This 
information specifies where the 
active workspace is stored when a 
)SAVE or )CONTINUE command is used. 
(When a stored workspace is loaded 
into the active workspace, the 
workspace ID and device/file 
number of the stored workspace 
is assigned to the active workspace.) 

The name of the user-defined 
functions in the active workspace. 

The names of the variables in the 
active workspace. 


The names of any suspended functions and 
the statement number where each 
function is suspended. For example: 


) SI 

FUNCTI0NAC5] 

functioned :p 

FUNCTIONCE63 

t 

Function Name 


#• 


Statement 2 of this function 
called FUNCTIONA. 

Statement Number 


The * (asterisk) indicates the suspended 
functions. The functions without an 
asterisk are functions (called pendent 
functions) that called the previous 
function. 

The same information as the )SI command 
plus the names local to each function. 




The system variables that provide information about the active 
workspace are: 


System Variable Information Provided 

OCT How different two numbers 

must be to be considered unequal. 

□10 The value of the index origin. 

□RL The starting value used in 

generating random numbers. 

□LC The statement number currently 

active. These statement numbers are 
the same as the statement numbers 
displayed by the )SI command. 

□WA The amount of unused storage 

in the active workspace. 

Note: The value of these system variables can be used in APL 

statements. For example: 

-►□LC causes a suspended function to resume execution with the next 

statement to be executed. 

The system functions that provide information about the system are: 

System Function Information Provided 

□ NL The names of the labels, variables, 

and user-defined functions in 
the active workspace 

□NC The classification (label, variable, 

or user-defined function) of a 
specified name 


ACTIVE WORKSPACE STORAGE CONSIDERATIONS 

Because the 5110 active workspace contains a fixed amount of 
storage, it is good practice to conserve as much storage as possible. 
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Data Types and Storage Considerations 

The following list shows how many bytes of storage are required for 
each data type that can be in the active workspace: 


Data Type 

Character constant 

Variable name (3 
characters or less) 

Variable name (4 
characters or more) 

Whole numbers that are 
equal to or less than 

2 31 -1 

Whole numbers that are 
greater than 2 31 -1 

Decimal numbers 

Logical data 


Number of Bytes Required 

1 byte per character 

12 + (4 x rank) bytes 
The rank is the number of 
coordinates (ppvariable). 

1 byte per character + 21 
bytes + (4 x rank) bytes 

4 bytes 

8 bytes 

8 bytes 

1 bit (1 byte contains 
8 one or zero bits) 


Note: Storage is always allocated in 4 byte increments. For example, 
the following illustration represents a portion of storage: 



In this example, 
storage has been 
allocated and used 
to this point. Also 
the storage required 
for the variable 
names A, X, and Y 
is already allocated. 


The statement 
A — 'ABCD' 
allocates and uses 
4 bytes of storage 


The statement 
X 'EF' 
allocates 4 bytes 
of storage, but 
uses only 2 bytes 


The statement 
Y 'GH' uses 
the remaining 
2 bytes. 











Following are some considerations that can be used to conserve 

storage: 

• Make all objects (variables and user-defined functions) not required 
for use outside of a user-defined function local to the function. 

• Store data in data files on tape or diskette and use an APL shared 
variable (see Input/Output Control) to transfer the data into the 
active workspace when required. 

• Clear suspended functions from the active workspace. 

• Collect user-defined functions by related operations and store each 
set into a workspace file on the media. Then when a certain set of 
related functions is required to process data in the active 
workspace, the stored workspace containing these functions can be 
copied into the active workspace. When the processing is done, the 
functions can be expunged (OEX) and another set of functions can 
be copied into the active workspace. 

• If a value consists of all 1's and 0's, store the value as logical data. 
For example, you have the following vector: 

VECTOR*-10 p < 2- :l.) 

VECTOR 

1 :l. :l. :l. 1. X X :l. l 1 


The result is a vector of ten 1's, and each 1 requires 4 bytes of 
storage. However, the vector can be changed to a logical vector as 
follows: 

VECTOR*-1. a VECTOR 
VECTOR 

:L X :l. 1 :l. 1 X :l. :l. 1 
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The result looks just like the previous result; however, only 2 bytes 
of storage are required. 

• Because each variable requires at least 12 bytes of overhead, an 
array of six elements requires approximately 60 bytes less storage 
than six separate variables. 

• Names of 3 characters or less require 8 bytes of storage in the 
symbol table (the symbol table is part of the active workspace 
where the names of all the symbols, including variables, 
user-defined functions, and labels, are stored). Names of 4 
characters or more require an additional 8 bytes plus 1 byte for 
each character in the name. 

Note: Even if an object is erased from the active workspace, the 
storage used for its name will not be available for use unless the 
contents of the active workspace are written to the media with a 
)SAVE command and then loaded or copied back into the active 
workspace. 

• Identical names that are local to more than one user-defined 
function do not require additional symbol-table space for each 
function. 

When the contents of the active workspace are written to the media 
by the )CONTINUE command, and that stored workspace is loaded 
into a different 5110 with a larger active workspace, the amount of 
available workspace (DWA) remains the same as it was when the 
contents of the active workspace were originally written to the media. 
To take advantage of the additional storage in the larger active 
workspace, write the contents of the active workspace to the media 
using the )SAVE command, then load the stored workspace back into 
the 5110. Also, for the same reason, a workspace written to the 
media by the )CONTINUE command cannot be loaded into a different 
5110 with a smaller active workspace. 



The following formula shows how much storage in the active 

workspace is required to perform an input or output operation to tape 

or diskette using an APL shared variable (see Input/Output Control)-. 

REQUIRED STORAGE = BUFFER + SHARED VARIABLE + 
OVERHEAD 

where: 

• REQUIRED STORAGE is the amount of storage that must be 
available in the active workspace (see DWA) before an input or 
output operation to tape or diskette can be performed. If there is 
not enough available storage, a WS FULL error occurs. 

• BUFFER is the amount of storage required by the data assigned to 
the shared variable. This storage is only used during the 
input/output operation. 

• SHARED VARIABLE is the amount of storage required for the data 
assigned to the shared variable. 

• OVERHEAD is the amount of storage used when the input/output 
operation is specified. The overhead is as follows: 

OUT and OUTF operations-812 bytes 

IN operation-792 bytes 

INR, IOR, IORH operations-356 bytes 
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ADDITIONAL STORAGE USING DISKETTE DATA FILES 

You can use a direct access data file to store variables that are not 
currently needed in the active workspace. These variables can then be 
removed from the active workspace (to conserve storage) and quickly 
read back into the active workspace as needed. You can use the 
following procedure to store variables for later use on a diskette data 
file: 


1. Establish a type M direct access data file (see Input/Output 
Control) using dummy records. The first dummy record written 
to the file should require as much diskette storage as the largest 
variable that is to be written to the file. For example, you might 
use the following user-defined function to establish a type M file 
with 256 bytes allocated for each record: 


vdummyi:i::i::iv 

V DUMMY;C;x; I 
:i>o 


You must specify the file 
ID enclosed in single quotes. 


r: 2 ::i xm osvo * c* 

i: 3 ::i c x • o u r f i i o o 8 :i: d «< r e a l . s t o r a g e ) t y p e = m ■ 
i:m:i oxitx<-c >/error 

C53 LOOP : 0256 p ' A ' 

r:.6:3 -><oxitx<-o /error 

i:?:i -»<20 > 3/- :i>:i. )/loop 

LSI OiO 

i:9II -XOXlfXH',) /ERROR 

i: :l.o:.l ‘ THE DATA FILE IS CREATED SUCCESSFULLY * 

i: 1.1.3 ~M) 

1 : 1. 2 :i E R R 0 R ! ■ E R R 0 R T H E R E T U R N C 0 D E IS : 1 , t X 

V 


2. Establish a pair of shared variables, and specify direct access 
input/output operations to the data file. For example, you might 
use the following user-defined function: 



VO PE 

Ni::n :iv 

^ - 


— 

v 


V OPEN 

file i: 

d; x 



\ 

r: i. 

1 X 1. 

"ISVO 2 

7 9 ' C TU. 

■SAVED AT 

SAVE 

■\ 

r.2 

3 "Ka/XX2)/E 

RROR 



\ 

C3 

1 CTLS 

AVE <" ’ T 

OR ID“ :: ( 

FILEID 

, ’ ) ‘ 

You must specify the 

\:m 

1 x*cf 

...SAVE 




file ID enclosed in 

C5 

1 •*< OX 

ltX)/E 

RROR 2 

[ON* 


single quotes. 

i :.6 

1 ■ sue 

CESSFUL operat: 


i: 7 

1 SAVE 

...I ST<r- 

t 1 p * ‘ 




i:e 

1 ■+ 0 






E9 

1 ERROR 

: • THE 

OFFER FA: 

[LED—T 

HE R 

ESULT IS: ‘ ,tX 

r: i. o :i -»o 






till ERROR 

2 ;• THE 

OPEN FA 

CLED . T 

HE R 

ETURN CODE: ’ ,tX 


V 


54 










3. Store the variable in the data file. For example, you might use the 
following user-defined functions: 


The left argument must be 1 to 


i:: 1 :i 
C 23 
II 3 II 


V 


expunge the variable name from 
the active workspace; otherwise, 
the left argument must be 0. 


VSAVECTPV, 

EXPUNGE GAVE VAR;MASK ;X 


The right argument is the variable 
name enclosed in single quotes. 


i < 0 ""[.'INC ‘ SA VELI ST 1 ) / 1 S A VELI ST*- 0 Op. 

i. < ( pSA VEL, I ST > C 1 3 < pVA R<-, VA R) / ’ SAVELISP-SAVELIST BY VAR ' 
i ^ v / M A S K <••(<< p S A V E LIS T > L 1 :i t V A R ) a .= B A V E L 1 ST ))/' S A V FI. I B T 
SAVELIS! BY VAR' 


1:4:1 nl<-(psavel:i:st)[:i:i 

L 5 :] DATSAVE<-.tVAR 

1: 6 :i CTLSAVE<- 1 , < (NLtVAR) a ,»BAVEL 1 ST) \ 1 

1: 7 :i ( 0 ? + 70 TLSAVE) /ER R 0 R 

r: a :i x<-o .. 

1:9:1 aEXPUNGE/ ' X<•*OEX ' * ' , VAR, 

C. 10 :.l ‘THE VARIABLE IS SAVED *,<X/*ANB EXPUNGED') 
Cl 13 0 

i: 12 3 E R R OR: ' S A V E F AIL E 0 ’ 


V 


vBYi:i;;i:iv 


i: 13 

V 

Z<~A BY B; ROW-- 

A<- (21 ( pA) , 1 1 ) pA 

C 23 


B<- < 2 t ( pB) , 1 1 ) pB 

i :33 


RGU *-1 t<pA)|” PB 

143 


A<- ( ROW , ’ 11 pA) t A 

i :53 


B*<ROW, '11 pB) tB 

L .63 

V 

Z<-A, B 


This function is used 
by the SAVE function. 


i: 13 
C 23 
C33 
C 43 
C 53 
C 63 
i: ? 3 
C 83 
C93 


4. At a later time, read the stored variable back into the active 
workspace. For example, you might use the following 
user-defined function: 

--The right argument is the 

VFETCH i: 0 :i V x variable name enclosed 

V Z<-F ETCH VAR; MASK .! NL in single quotes. 

* < 0 = LI N C 'SAVE LIS T ' ) / N 0 T F 0 U N D 

* < < PVAR, VAR) >NL«-11 pSAVELIST ) /N0TF0UND 
~H » v / M A S K *• (N L t V A R ) a , S A V E L I S T) / N 0 T F 0 U N D 
CTLSAVE<“0 , MASK \ .1. 

•* < O^hh/CTLSAVE ) / 0 
Z<-V AR, ' IS'"FOUND* 
a VAR, * f-DATSAVE * 

+0,DATSAVE*- i 0 " 

NOTFOUNDlZ^VAR, * IS NOT FOUND IN THE FILE* 
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5. 


Before the contents of the active workspace can be written to the 
media by the )SAVE command, the input/output operations to the 
data file must be terminated. For example, you might use the 
following user-defined function: 

vclo9Fi::i:i::iv 

y CLOSE FILEXD _ You must specify the file ID 

i:; l :;i CTLSAVE*- 0 enclosed in single quotes. 

E!2::i X«-C TLSAVE 

c 3 ::i ••>( ox x t x‘> /'error 

c 1+ :i ' T H E FIL E 0 L 0 S E D S U C C E S S F U L L Y ' 

t: 5 ::i ■+ o 

i:: 6 ::i e r r q r : ■ t h e f :i: l f. n i d n o t c l o s e. t h e r e t u r n c o d e j. b : ' 

1:7:1 x 

v 

Note: If you want to use the data file at a later time, do not 
terminate the input/output operations. Instead, you should use 
the )CONTINUE command to write the contents of the active 
workspace to the media and then use the )RESUME command to 
reestablish the input/output operations at a later time. 

This procedure works as follows, using the sample user-defined 
functions: 


)HARK 10 1 B 
MARKED 0008 0010 


File number 8 is used as 
the data file. 


THE 


DUMMY-*— 
DATA FILE 


IB C R E A T E D B U C C E B S F U L L Y 


Create the data file 
used to save the 

\/ariahlp<; 


0 PEN ’ REAL . STORAGE -The data file is ready 

SUCCESSFUL OPERATION for input/output operations. 


IN F 0 R M A 10 N *■ ’ A P R 0 G R A H M X N G 


A variable to 
be saved for later 














The variable is to be expunged. 

/ 

:l. SAVE ‘ INFORMATION ' 

THE VARIABLE IS SAVED AND EXPUNGED 


INFORMATION 

VALUE ERROR -_ 

INFORMATION 


The variable no longer exists in the 
active workspace. 


FETCH 

INFORMATION 


INFORMATION 
S FOUND 


INFORMATION 

A PROGRAMMING LANGUAGE 



Read the variable back into 
the active workspace. 


API.,*- ‘ DATA' 


HE 


0"SAVE 
VARIABLE 


‘ A PL ' 

IS SAVED 


The variable is saved, but it is 
not expunged. 


A PL 

DATA 


FETCH 'NAME 
NAME IS NOT FOUND 


A variable not saved in the 
data file. 

IN THE FILE 



THE 


CLOSE 'REAL.STORAGE* 

LE CLOSED SUCCESSFULLY 


"Before the active workspace 
can be saved, the data 
file must be closed. 
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Chapter 5. Console Control 


The 5110 console consists of a keyboard, a display screen, and 
switches. 



In this chapter, the following topics concerning the 5110 console are 
discussed: 

• Controlling the input from the keyboard 

• Controlling the position of the information on the display screen 

• Sounding the audible alarm 

• Console control through a user-defined function 
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CONTROLLING THE INPUT FROM THE KEYBOARD 

The following illustration shows the positions on the alphameric 
keyboard of the uppercase alphameric characters, the APL symbols, 
the APL keywords, and the special character combinations: 


( )LOAO) SAVE DC C O NT DC ) LIB *| [ ) FNS ) (TvARS DC copy")[ iwsid l ()OUTSEL)fTMark )[ j 


COPY 

DISPLAY 


fPELETE)fINSERT) 



° V 

u Tli T o TIp 


IvT 




EXECUTE 




III H J I I K I L J [ . 1 # 

\/ * n \l/coAl/~AL< Al/Tv 


V l, B 

/nsvo\|/ 


_\l/ _Al / M/ 




\i 


n 


Note: The special character combinations are engraved on the front of 
the appropriate key on the 5110 keyboard. If the 5110 is a 
combination APL/BASIC machine, the special APL character 
combinations are below the BASIC keywords. 


When you turn the 5110 power on, the 5110 is in standard APL 
character mode. That is, you enter the uppercase alphabetic 


characters without using the shift 



key, the APL symbols 


using the shift key, and the APL keywords and special character 
combinations using the CMD key. For example, if you press: 



1/ nuA\| 


The character A is entered from 
the keyboard. 





The character a is entered from 
the keyboard. 


The character combination DWA 
is entered from the keyboard. 




































You can also enter lowercase alphabetic characters from the keyboard. 
To do this, you use one of the following procedures: 

• Use the keying sequence: 

1 . Press the flt key. 

2. Hold down the 
down) key. 

• Enter the following statement to use the console control (DCC) 
system function: 



(shift) key and press the 


(scroll 


/ A 3 as the left argument specifies that the DCC system 
function is used to change the character mode. 

3 OCC 1 


■Specifies lowercase alphabetic characters. (See the 
IBM 5110 APL Reference Manual, SA21-9303, for a 
complete description of the DCC system function.) 


Once the 5110 is in lowercase character mode, you enter the 
lowercase alphabetic characters without using the shift key, the 
uppercase alphabetic characters using the shift key, and APL 
symbols using the CMD key. For example, if you press: 

The character a is entered from 
the keyboard. 





The character A is entered from 
the keyboard. 



The character a is entered from 
the keyboard. 


You cannot enter the special character combinations using the CMD 
key and a single key when the 5110 is in lowercase character mode. 
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The 5110 remains in lowercase character mode until: 


• The system power is turned off. 

• The RESTART switch is pressed. 

• One of the following procedures is used to change the keyboard 
entry mode to standard APL characters: 

- Perform the keying sequence: 

1. Press the MR key. 


2. Hold down the 


up) key. 

Enter the statement: 


(shift) key and press the 


(scroll 


3 OCC 0 


Specifies standard APL character mode 


CONTROLLING THE INFORMATION ON THE DISPLAY SCREEN 

You can control the information and the position of the information on 
the display screen by using: 

• The scroll up and scroll down keys 

• The DOC (console control) system function to turn display on or off 

• The IDCC system function to scroll the information on the display 
screen up or down 

• A pair of shared variables 

You are already familiar with using the scroll up and scroll down keys 
to position the information on the display screen. How to use a pair of 
shared variables to read and write data at any position on the display 
screen is discussed in detail under Input/Output Control. How to use 
the DCC system function to control information on the display is 
discussed in this section. 



Using the DCC System Function to Control on the Display Screen 

In the previous discussion on controlling the input from the keyboard, 
the DCC function was used to place the 5110 in lowercase alphabetic 
character mode. The DCC function can also be used to: 

• Turn the display screen on or off during the execution of a 
user-defined function. The primary advantage in turning the display 
screen off is that the 5110 internal processing speed is increased by 
approximately 18%. 

• Scroll the information on the display screen up or down. 

To turn the display screen off during the execution of a user-defined 
function, the left argument of the DCC function must be a 1 and the 
right argument must be 0. The display screen remains off until one of 
the following occurs: 

• The user-defined function completes execution. 

• The DCC function is used to turn the display screen on again (both 
the left and right arguments are specified as 1). 

• A later statement in the user-defined function generates a result to 
be displayed. 

Since the DCC function generates an explicit result, that result must be 
assigned to a variable to prevent the display screen from being 
immediately turned on and the result displayed. For example: 

n.::i rh. occ o 

When the DCC function is used to scroll the display screen up or 
down, the left argument must be 4 and the right argument specifies 
the number of lines to scroll up or down. For example: 


R<-4 PC 

:c 8 

Scrolls the information on the display screen 
up 8 lines 

r<-m- pc: 

:C '"3 

Scrolls the information on the display screen 
down 3 lines 


In the previous examples, the explicit result of the DCC function is 
assigned to a variable. Otherwise, the explicit result is displayed after 
the DCC function scrolls the display screen up or down. 
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SOUNDING THE AUDIBLE ALARM 


Another use of the DCC function is to sound the audible alarm feature, 
if installed. To do this, the left argument must be a 2 and the right 
argument is: 

• A 1 to sound the audible alarm. The audible alarm remains on until 
any input is entered from the keyboard or the DCC function is used 
to turn the audible alarm off (the right argument is a 0). For 
example: 


R<-2 OCC 1 0 :l 0 1 0 


turns the audible alarm on and off three times. The on/off interval 
is approximately 0.006 second. 

• A vector of 2's, where each 2 sounds the audible alarm for 
approximately 1/4 second. For example: 

R<-2 OCC 2 2 2 2 

sounds the audible alarm four times for approximately 1/4 second 
each time. 



CONSOLE CONTROL THROUGH A USER-DEFINED FUNCTION 

The DCC system function, like any other system function, can be 
executed from a user-defined function. This technique allows the 
following console control operations to be initiated from a 
user-defined function: 

• Turn the display screen on or off. 

• Sound the audible alarm. 

• Set the keyboard input to standard APL characters or lowercase 
alphabetic characters. 

• Scroll the display screen up or down. 

• Set the left tab position for printed output (see Printer Control for 
more information on setting the left tab position). 


Following is an example of initiating console control operations from a 
user-defined function: 


i:: i ::i 
C2."J 
i:3:i 

cm-3 

1:5:1 

1:6:1 

1:7:1 

\:b:\ 

1:9:1 

1:10 :i 

1:: :i. 1 :i 

C 123 

1 : 0:1 

C 1 M -3 

i: .1.5:i 

Cl 61 

i: 1.73 


VCGNTROLClilV 
CONTROL;NAME 
R<-4- OCC 16 

Rf-3 OCC U - 

‘ENTER YOUR 
NAME*!!! 

R<-3 OCC 0-— 
R< - ! l- OCC 10 
l!H- ‘ WELCOME ' 


Scroll the display screen up 16 lines. 


; STATEMENT;R 


Set the keyboard input to lowercase 
alphabetic character mode. 


FIRST AND LAST NAME' 


Set the keyboard input to standard 
APL character mode. 


CM-NAME 

’, ENTER A STATEMENT 
ROCC 2 
STATEMENT*!!] 

R*M- OCC 2 

R*1. OCC 0 -»--- 

R<-a STATEMENT 

'THE RESULT IS: -' 

R 

R<-2 OCC 2 2 2 2 


TO BE EXECUTED. 1 


_/Turn the display screen off to improve 
internal performance when the next 
statement is executed. 


The display screen is turned on again when 
output is sent to the display screen. 


Sound the audible alarm when the user-defined 
function has completed execution. 


Console Control 65 







66 



Chapter 6. Library Control 


The tape or diskette files where you store information is your library. 
In this chapter, the following topics concerning the 5110 library control 
are discussed: 

• Determining the size of a tape or diskette file 

• Writing data to a tape or diskette file 

• Getting data from a tape or diskette file 

• Controlling files in the library 

• Maintaining data security 

References are made to some of the 5110 system commands; for 
example, the )MARK command or the )RESUME command. See the 
IBM 5110 APL Reference Manual, SA21-9303, for a complete 
description of the system commands. The description includes the 
required syntax for each system command. You must use the proper 
syntax to enter a system command so that the 5110 will accept that 
command. 
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DETERMINING THE SIZE OF A TAPE OR DISKETTE FILE 


Before information can be stored on the media (tape or diskette), the 
media files must be formatted by the )MARK command. When using 
the )MARK command, you can use the following formulas to 
determine the maximum size a file should be marked. The formula for 
a workspace file [the contents of the active workspace were written to 
the storage media with a )SAVE or )CONTINUE command] is MAXSIZE 
= T3 + (CLEAR-ACTIVE) 1024, where: 

• MAXSIZE is the maximum amount of media storage (number of 
1024-byte blocks) that would be required to write the contents of 
the active workspace to the media. 

• CLEAR is the value of DWA in a clear workspace. 

• ACTIVE is the value of DWA just before the contents of the active 
workspace are written to the media. 

The formula for a data file (data written to the media using an APL 
shared variable) when all of the data is contained in the active 
workspace is MAXSIZE = T (WITHOUT-WITH) -r 1024, where: 

• MAXSIZE is the maximum amount of media storage (number of 
1024-byte blocks) required to write the data to the media. 

• WITH is the value of DWA with the data in the active workspace. 

• WITHOUT is the value of DWA before any data to be written to 
tape or diskette was stored in the active workspace. 

There is no formula for determining what size to mark a data file when 
the data is written to the media as it is entered from the keyboard. 

The amount of storage required depends upon how much data is 
entered from the keyboard and what type of data is used. For 
information on how many bytes of storage are required by the various 
types of data, see Storage Considerations in the Active Workspace 
Control chapter. 



WRITING DATA TO A TAPE OR DISKETTE FILE 

You can write data to a file by using the )SAVE command, the 
)CONTINUE command, or an APL shared variable. The )SAVE or 
)CONTINUE commands are used to write the contents of the 5110 
active workspace to a file. An APL shared variable is used to write 
individual data records to a data file (shared variables are discussed in 
detail under Input/Output Control ). 

The following list shows the advantages and disadvantages of using 
the )SAVE command versus the )CONTINUE command. You should 
consider these advantages and disadvantages when choosing which 
command you are going to use when writing the contents of the 
active workspace to the media. 


Using the )SAVE Command 

Advantages: 

• The stored workspace can be loaded into a 5110 that has a smaller 
active workspace than the original active workspace, providing the 
stored workspace does not require more storage than is available in 
the smaller active workspace. 

• The additional storage is available to the user when the stored 
workspace is loaded into a 5110 that has a larger active workspace 
than the original active workspace. 

• The symbol table is Cleared of unused or expunged symbol 
references. 

• The )COPY and )PCOPY commands can be used to copy specified 
variables or user-defined functions from the stored workspace. 

Disadvantages: 

• The active workspace is not written to the media as fast as when 
the )CONTINUE command is used. 

• The stored workspace is not loaded into the active workspace as 
fast as when the )CONTINUE command is used to write the 
workspace to the media. 

• If the active workspace contains suspended functions or open data 
files exist, the active workspace cannot be written to the media. 
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Using the CONTINUE Command 

Advantages: 

© Even if the active workspace contains suspended functions or open 
data files exist, the active workspace can be written to the media. 
Any open data files or suspended functions can be restored by the 
)RESUME command. The )RESUME command is discussed in more 
detail under Getting Data from a Tape or Diskette File in this 
section. 

© The active workspace is written to the media faster than when the 
)SAVE command is used. 

© The stored workspace is loaded into the active workspace faster 
than when the )SAVE command is used to write the workspace to 
the media. 

Disadvantages: 

• The )COPY and )PCOPY command cannot be used to copy variables 
or user-defined functions from the stored workspace. 

• The stored workspace can only be loaded into a 5110 with an active 
workspace at least as large as the original active workspace. 

• The additional storage is not available to the user when the stored 
workspace is loaded into a 5110 that has a larger active workspace 
than the original active workspace. 



GETTING INFORMATION FROM A TAPE OR DISKETTE FILE 

You can read information from a tape or diskette file by using the 
)LOAD, )RESUME, )COPY, )PCOPY commands, or an APL shared 
variable. The )LOAD, )COPY, )PCOPY, and )RESUME commands are 
used to place the contents of a stored workspace into the 5110 active 
workspace. An APL shared variable is used to read individual data 
records from a data file {shared variables are discussed in detail under 
Input /Output Control ). 

Generally, you use the )LOAD command to replace the contents of the 
active workspace with the contents of a stored workspace. However, 
if there were shared variables or suspended functions in the active 
workspace and the )CONTINUE command was used to write the active 
workspace to the media, the )RESUME command reads the stored 
workspace into the active workspace and reestablishes the shared 
variables and/or suspended functions. That is, the system 
environment is reestablished as it was when the )CONTINUE command 
was issued. 

Using the )CONTINUE and )RESUME commands allows you to work 
with shared variables or suspended functions, write the active 
workspace to the media, and then reestablish the system environment 
at a later time so that you can continue working with the shared 
variables and/or suspended functions. See The )RESUME Command 
in the IBM 5110 APL Reference Manual, SA21-9303, for a description 
of how the shared variables are reestablished. 

If a workspace was stored on the media using the )SAVE command, 
you can copy all or part of that workspace into the active workspace 
by using the )COPY or )PCOPY commands. The )COPY command 
copies all or specified objects (variables or user-defined functions) into 
the active workspace and replaces any objects in the active workspace 
that have the same name. The )PCOPY command copies all or 
specified objects into the active workspace; however, any objects in 
the active workspace that have the same name are not replaced (they 
are protected). The )COPY and )PCOPY commands allow you to read 
more than one stored workspace or parts of more than one stored 
workspace into the active workspace without replacing objects already 
existing in the active workspace. 
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CONTROLLING THE FILES IN THE LIBRARY 


Once you have stored several workspace and data files on a tape or 
diskette (your library), you might want to know what files you have in 
your library. You can use the )LIB command to display the file headers 
for a specified tape or diskette. The file headers provide you with 
such information as the file number, the file ID, the file type, and so 
on. See The )LIB Command in the IBM 5110 APL Reference Manual, 
SA21-9303, for a description of the information contained in the file 
header. 

When there are files on tape or diskette that contain data that is no 
longer required, you can mark these files unused by issuing the )DROP 
command. Once a file is marked unused, any data in the file can no 
longer be read into the 5110 and the file is available for other uses. 

Also, if a diskette file is no longer required, you can make the file 
space available for reallocation by issuing the )FREE command. This 
allows the file space on the diskette to be used for other numbered 
files by the )MARK command. See Diskette Concepts for more 
information on how files are allocated on a diskette. 



DATA SECURITY 


You are primarily responsible for the security of any sensitive data. 

After you are through using the 5110, you can remove the data in the 

active workspace by one of the following: 

• Using the )CLEAR command to clear the active workspace 

• Pressing the RESTART switch 

• Turning the POWER ON/OFF switch to off 

There are several methods available for protecting or removing 

sensitive data on a tape or diskette. These methods are: 

• Assigning a password to the workspace when the system is writing 
the active workspace on the media. 

• Rewriting a file, which makes the old data inaccessible. 

• Filling a data file with meaningless data. For example, the following 
user-defined function fills file 4, a data file named DATA on tape 1, 
with zeros: 



\ 

/SEC 

IJ-RITYJ AJB 

i:: i :i 

:l. i 

•JSVO 

‘A* 

1:2:1 

A*- 

OUT 

1004 ID* ( DATA ) 

1:3:1 

B<~: 

1.0 :l. 

0 0 0 p0 

1: m- :i 

UR 

A*B 


1:5:1 

■> < a r: 11 

= 0)/URV 


• Setting the tape cartridge SAFE switch in the SAFE position to 
prevent someone from accidently writing on the tape. 

• Using the )PROTECT command to prevent someone from accidently 
writing on a diskette file. 

• Using the )VOLID command to prevent unauthorized access to the 
diskette files. 

• Storing the tape or diskette in a secure place. 
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Chapter 7. Tape Concepts 


There are 204K bytes (IK = 1024 bytes) of tape storage available on 
an IBM Data Cartridge. This tape storage is used for file headers, 
workspace files, and data files. In this section, the following topics are 
discussed: 

• How to format the tape 

• How to determine the amount of storage on a tape cartridge that is 
actually available to you 


FORMATTING THE TAPE 

You must use the )MARK command to format files on the tape before 
you can store the contents of the active workspace or data records on 
the tape. For example: 


) MARK 


10 5 1. 


Starting File Number 
‘Number of Files to Mark 


Size of the Files in Increments of 1,024 (IK) 
Bytes. In this case, the size of the marked 
files is 10, 240 (10 x 1,024) bytes. 


Once the previous )MARK command is successfully completed by the 
5110, the tape is formatted as follows: 
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The file headers contain information about the file, such as the file 
number, file name, file type, and so on. Each file header requires 512 
bytes of tape storage. 

Now, if you want to format additional files on the tape, you must use 
the )MARK command again. For example: 


-Starting File. Remember, in this 

example, five files are already 
formatted. 

Number of Files to Mark 


The tape is now formatted as follows: 


File 6 Header 




File 6 is formatted Unformatted 

after file 5. Tape 


When the information in a tape file is no longer needed, you can use 
the )DROP command to mark the file unused so that the file is 
available for other uses. However, once a file is formatted, you 
cannot increase the size of the file without re-marking the file. When 
you re-mark an existing file, any information in the files following the 
re-marked file is lost. For example, assume you want to increase the 
size of file 4 on the tape from 10K to 15K: 



You want to increase the size 
of file 4 by 5K. 





After the command: 


) HARK 


File Size 

Number of Files to Format 
Starting File Number 
/ 



is successfully completed, the tape is formatted as follows: 


4 

. / 

File 4 now contains This file header now indicates the end of 

15K bytes of tape storage. the marked tape, and any data following 

this file header is lost. 



A formatted tape has the following characteristics: 

• The files are of variable length from 1K to 200K, in 1K increments. 

• The files can be randomly accessed; that is, you can read a file 
without having to read the previous file. However, the data in the 
files must be accessed sequentially. 

• It can contain both workspace and data files. 

• It can contain both APL and BASIC files. 
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DETERMINING THE AMOUNT OF STORAGE AVAILABLE ON A TAPE 
CARTRIDGE 


There are approximately 204K bytes of storage on each tape cartridge, 
but the amount of tape storage actually available to you depends on: 

• How many files are marked (formatted) on the tape 

• How the data files were written to tape 

Each file on a tape cartridge requires one 512-byte file header. 
Therefore, as you mark more files on a tape cartridge, more tape 
storage is used for file headers. For example, if you mark one 3K file 
on a tape, 512 bytes of tape storage are used for the file header. 
However, if you mark three IK files on tape, 1,536 bytes of tape 
storage are required for the file headers. 


One 3K File 



Three 1K Files 


0.5K 

IK 

0.5K 

IK 

0.5K 

IK 


Notice that, in each case, a total of 3K bytes of tape storage is 
allocated for tape files. However, in the second case, an additional 1K 
bytes more of tape storage are used. 

The amount of data you can store in a data file depends on how the 
data is written to the data file. (See Input/Output Control for a 
complete description of writing data to data files.) For example, when 
you first write data to a data file (an OUT operation), the individual 
records are sequentially written to tape starting at the beginning of the 
data file. Once these records are written to tape, the data file might 
look like this: 


Data File 





Now, assume you add data to the data file at a later time (an ADD 
operation). The new data starts at the first 512-byte boundary after 
the last record in the data file. The tape storage between the last data 
record and the additional data records is unavailable for use. Once the 
new data records are written to tape, the data file might look like this: 


Data File 


512-Byte Boundaries (tape storage is 
^divided into 512-byte segments) 



the Data File Tape Storage Tape Storage 


As you add more data to the file, it is possible for more tape storage 
to become unavailable. You can compress the data in the data file (use 
the unavailable storage) by first reading all the data records from the 
file and then writing the data records back to the file, starting at the 
beginning of the data file (an OUT operation). 
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Chapter 8. Diskette Concepts 


The IBM diskette is a thin, flexible disk permanently enclosed in a 
semirigid, protective, plastic jacket. When the diskette is properly 
inserted in the diskette drive, the disk turns freely within the jacket. 
The diskette is inserted in the diskette drive as follows: 



lower corner as the diskette 
is inserted in the diskette drive. 
The diskette drive door must be 
closed and latched after the 
diskette is inserted. 


Data is written on the diskette at specific locations (addresses) by the 
system. These addresses provide direct access to specific 
information. Data written at an address remains there until it has been 
replaced by new data. To read data, the desired address is found and 
the data is read into the 5110. 

Before being shipped to a user, each IBM-supplied diskette is 
initialized. Initialization is a process whereby label information and data 
addresses are recorded on the diskette. In this chapter, the following 
topics are discussed: 

• Diskette wear 

• Diskette addressing and layout 

• Diskette types and formats 

• Diskette initialization 
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« Diskette volume ID, owner ID, and access-protect indicator 

« Diskette file information, such as file ID, write-protect indicator, and 
organization 

o Reallocation of diskette file space 
o Amount of storage available on a diskette 


DISKETTE WEAR 

The use of flexible diskette storage provides some significant 
advantages, such as low cost, compact size, multiple system functions, 
and ease of media handling and storage. It should be recognized, 
however, that during recording and reading, the read/write head is in 
contact with the media, causing diskette wear over time. Variations in 
the rate of wear will depend on the particular operating environment 
and application characteristics. Care in the storage, use, and handling 
can also affect diskette life. (See guidelines in the IBM 5110 APL 
Reference Maual.) Excessive wear, handling, or contamination can 
cause possible failures in recording and/or reading. 

Ultimate wear is to some extent dependent upon total usage of 
individual tracks. Care taken to distribute data so that accessing 
occurs over the entire recording surface with about the same 
frequency can extend the useful life of the diskette. Actual experience 
with individual applications and environments will allow development 
of guidelines as to when the media should be replaced. 

Unpredictable circumstances such as contamination or severe handling 
can cause an early error to occur. 

For the previous reasons, consideration should be given to providing 
an adequate recovery plan, such as: 

• Backing up critical programs and data files on a second diskette for 
use in the event of an error on the primary diskette. 

• Periodically moving frequently used files to alternate locations on 
the diskette (see the copy function in the IBM 5110 Customer 
Support Functions Reference Manual). 



DISKETTE ADDRESSING AND LAYOUT 

A diskette address consists of a combination of cylinder number, head 
number, and record number as follows: 

CC H RR 

t I 

1 -Record (sector) Number. The sector into which the data 

is to be written or from which the data is to be read. 

-Head Number. The side of the diskette on which the data is to 

be written or from which it is to be read. This number is hex 0 
for all one-sided diskettes and for side 0 of two-sided diskettes. 
The number is hex 1 for side 1 of two-sided diskettes. 

-Cylinder Number. This number identifies the cylinder onto which a 

physical record is written or from which it is read. 


Track and Cylinder 

A track is the recording area on a single diskette that passes the 
read/write head while the disk makes a complete revolution. The 
read/write head is held by a carriage that can be moved to 77 distinct 
locations along a straight line from the center of the disk. Therefore, 
each diskette has 77 concentric tracks on which data can be stored. 



The diskette drive for two-sided diskettes has a read/write head on 
each side. Each track on side 0 of a two-sided diskette has an 
associated track on side 1. 

A cylinder is one track on a one-sided diskette or a pair of associated 
tracks (the corresponding tracks on opposite sides of the diskette) on 
a two-sided diskette. There are 77 cylinders (numbered 0 to 76) on a 
diskette. 
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Sector 


A sector is a portion of a cylinder. All sectors on a single cylinder are 
the same size, and the number of sectors on a cylinder depends on 
the number of bytes per sector (see Diskette Types and Formats in 
this chapter). 



Index Cylinder 

Cylinder 0 is called the index cylinder and is reserved for information 
describing the diskette and its contents. It contains information about 
the diskette, such as volume and owner identification. The index 
cylinder also contains information associated with each file on the 
diskette. This includes the name of each file and the addresses 
associated with the file extents. An extent is the maximum space a file 
can occupy. The address at the beginning of this space is called the 
beginning of extent (BOE). The address at the end of this space is 
called the end of extent (EOE). A file may not use all of the space 
allocated for it by the BOE and EOE addresses; therefore, another 
address for end of data (EOD) exists. 

Actual space being used for data 


BOE EOD EOE 

l_1_i 

N> t J 

Area allocated for the file (extent) 


The EOD address is used to identify the next unused area within the 
extent or to indicate that data has been written to the EOE address. 
(See the diskette initialization function in the IBM 5110 Customer 
Support Functions Reference Manual, SA21-9311, for a complete 
description of the index cylinder.) 




Alternate Cylinders 

The last two cylinders (75 and 76) are reserved for use as 
replacements (alternate cylinders) for defective cylinders. The 
remaining cylinders (1 through 74) are used for storing data. 


DISKETTE TYPES AND FORMATS 

The 5110 uses three types of diskettes; the one-sided diskette (1), 
with data recorded on just one side; the two-sided diskette (2), with 
data recorded on both sides; and the two-sided diskette (2D), with 
data recorded on both sides at double density. The diskettes are 
initialized (see Disk Initialization) into various formats consisting of: 

• The number of sectors per cylinder 

• The number of bytes per sector 
The possible diskette formats are: 


Sectors 

Sectors 

Bytes 

per 

per 

per 

Track 

Cylinder 

Sector 

p26 

26 

128 

Diskette 1 1 15 

15 

256 

L8 

8 

512 

[26 

52 

128 

Diskette 2 1 15 

30 

256 

L 8 

16 

512 

p6 

52 

256 

Diskette 2D 1 15 

30 

512 

L8 

16 

1,024 


Note: The diskette types (1, 2, or 2D) are identified on the diskette 
label, and the )VOLID command can be used to determine the bytes 
per sector (record size). 
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DISKETTE INITIALIZATION 


The diskettes must be initialized before they can be used for storing 
data. All IBM-supplied diskettes are initialized before they are shipped 
to a customer. Reinitializing is not required unless: 

• The diskette was exposed to a strong magnetic field. 

• A defect occurred in one or two cylinders. In this case, initialization 
can be used to take the bad cylinder(s) out of service and use one 
or two of the alternate cylinders. 

• A sector sequence other than the sequence existing on the diskette 
is desired. 

• A format (number of sectors per cylinder) other than the existing 
format is desired. 

See the IBM 5110 Customer Support Functions Reference Manual , 
SA21-9311, for a description of the diskette initialization function. 


VOLUME ID, OWNER ID, AND ACCESS PROTECTION 

Each initialized diskette has volume ID, owner ID, and an 
access-protect indicator. The volume ID is the identification of the 
diskette volume, and the owner ID is the identification of the diskette 
volume owner. The access-protect indicator is used to prevent 
unauthorized access (reading and writing) to the diskette volume. 

The )VOLID command is used to display or change the volume ID and 
owner ID or to change the access-protect indicator. 



FILE ID 


Each file header on a formatted (marked) diskette has a file ID 
(identification). When the diskette files are formatted, a file ID is 
automatically generated, even though the files are unused. For 
example, the file name for file 1 is SYS0001. 

The )FILEID command can be used to display or change a file ID. 

The file ID for a stored workspace must be a simple name. A simple 
name must begin with an alphabetic character and can be up to eight 
alphameric characters. For example: 

SALES200 

The file ID for a data file can be a simple or complex name. A 
complex name is two or more simple names with each name 
separated by a period. A complex name cannot exceed 17 characters 
including the period. For example: 

SALES200.DATA 

SALES. DATA. DIST12 


DISKETTE FILE WRITE PROTECT 

Each file header contains a write-protect indicator. When the 
write-protect indicator is on, no data can be written to the file. The 
JPROTECT command invokes or removes the write-protect indicator 
for a diskette file. 
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DISKETTE FILE ORGANIZATION 


You use the )MARK command to format files on the diskette before 
you can store workspaces or data records on the diskette. For 
example: 


)MARK 10 



-Diskette Drive 1 

Starting File Number 


Number of Files to Format 


Size of the Files in Increments of 1,024 (IK) Bytes. In this case, 
the size of the marked files is 10,240 ( 10 x 1,024) bytes. 


Unlike tape files, the diskette files are not always formatted 
sequentially on the diskette. For example, file 2 might be on cylinder 
3, file 3 on cylinder 9, and file 4 on cylinder 7. You can control the 
location of a file on the diskette only by using a totally unmarked 
diskette and issuing )MARK commands in the same order as the files 
are to be formatted on the diskette. 

When the information in a diskette file is no longer needed, you can 
use the )DROP command to mark the file unused so that the file is 
available for other uses. However, once a file is formatted, you cannot 
increase the size of the file without re-marking the file. Reallocating 
diskette file space is discussed next. 
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REALLOCATING DISKETTE FILE SPACE 

Unlike tape files, when you re-mark an existing diskette file, no other 
diskette files are affected. When you re-mark a diskette file to 
increase the size, the file space presently allocated to that diskette file 
is made available for other files being marked. The remarked file will 
then be located on the diskette where there is enough continuous 
storage available for that file. For example, assume you want to 
increase the size of file 4 from 10K to 15K by issuing a )MARK 15 14 
11 command: 


Disk 

Cylinder 



for File 4. 

Once the file space previously occupied by file 4 is available, that file 
space will be used by a subsequent )MARK command that marks a file 
of 10K or smaller. 

After the )MARK command is successfully completed, file 4 is 
formatted on the diskette at a location where at least 15K of 
continuous storage is available. 


Diskette 

Cylinder 



20K of unallocated diskette storage was 
available at this location before the 
)MARK command was issued. 


Diskette Concepts 89 









AMOUNT OF STORAGE AVAILABLE ON A DISKETTE 


The amount of storage available on a diskette depends upon: 

• Whether data can be recorded on just one side or on both sides of 
the diskette 

• The number of sectors per cylinder 

• The number of bytes per sector 

Each diskette has 77 cylinders. Cylinder 0 is the index track and is 
reserved for information (file headers) about the diskette files. 
Cylinders 75 and 76 are alternate cylinders that are used as 
replacements for bad cylinders. This leaves cylinders 1 through 74 
available for data storage. The following chart shows the amount of 
storage available with the different types of diskettes: 



Sectors 

Bytes 

Available 


per 

per 

Storage in Bytes 


Cylinder 

Sector 

(cylinders 1-74) 


26 

128 

246,272 

Diskette 1 

15 

256 

284,160 


8 

512 

303,104 


52 

128 

492,544 

Diskette 2 

30 

256 

568,320 


16 

512 

606,208 


52 

256 

985,088 

Diskette 2D 

30 

512 

1,136,640 


16 

1,024 

1,212,416 


Although the previous chart shows the maximum amount of diskette 
storage, the amount of diskette storage actually available to you 
depends on: 

• The number of files and the size of the files marked on the diskette 

«> The types of data files that are written to the diskette 

« The allocation of file space as the result of previous )MARK and 
)FREE commands 



Number and Size of Diskette Files 

The diskette volume/owner identification (7 sectors) and file header 
information are contained on the index cylinder. The remaining 
cylinders on each type of diskette can have the following maximum 
number of files: 


Diskette 1 Diskette 2 Diskette 2D 


Maximum Number 

of Files 19 45 71 


Note: For a type 2D diskette, see the disk initialization function in the 
IBM 5110 Customer Support Functions Reference Manual, SA21-9311, 
for information on how to get additional file headers. 


If you mark the maximum number of files without using all the 
available file space, the remaining file space becomes unavailable for 
storing data. For example, assume you have an unmarked Diskette 1 
with 128 bytes per sector. This diskette has 246,272 bytes available 
for storing data; however, you issue the following command: 


) MARK 


10 1.9 1 U 


1 -In this example, diskette drive 1 is used. 

-The starting file number. 

The number of files to be marked. 

The size of each file to be marked. 


This command marks the diskette with the maximum 19 files. Because 
each file is 10K bytes, a maximum of 190K (194,560) bytes of storage 
is allocated for the files. Now, if you subtract the allocated diskette 
storage from the available diskette file space: 


246,272 

-194,560 

51,712 


For this example, this much diskette storage is 
unavailable for you to store data. 


Types of Data Files 

How to generate the various types of diskette data files is discussed 
under Input/Output Control. Two types of data files can cause 
diskette file storage to be unavailable for storing data: U (unblocked) 
and M (mixed). 
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Type U Data File 


A type U data file specifies that each record in the file starts at the 
beginning of a sector and that a record cannot span from one sector 
to another. 


Data File 



The sectors on a diskette can be 128, 256, 512, or 1,024 bytes. If a 
record does not require the number of bytes available in a sector, the 
remaining portion of the sector is unavailable for data storage. 


Beginning of 256-Byte Sectors 



To obtain the maximum available storage for a type U data file, you 
should do one of the following: 

• Write records to the file that are the same size as (or as close as 
possible to) the sector size. 

• Use a diskette whose sectors are initialized (128, 256, 512, or 1,024) 
nearest to the record size. Remember, the entire record must fit in 
one sector. 


92 



Type M Data File 


A type M data file specifies that each record in the file requires the 
same amount of file storage as the first record written to the file. That 
is, the first record determines the characteristics of the file. Any 
record written after the first record cannot be larger than the first 
record. 

Data File 


Beginning of the Data File 


100 Bytes 

100 Bytes j 

100 Bytes 

100 Bytes 

100 Bytes 

K 

v , -——■-- 

H 


\ 


The first record used this amount of storage; 
therefore, any following records are allocated 
the same amount of file storage. 

If any of the following records do not require as much storage as the 
first record, the remaining portion of the storage allocated for the 
record is unavailable for data storage. 


Increments of 100 bytes as specified by the first 
record written to the file 



To obtain maximum available storage for a type M data file, you 
should make the records as uniform in size as possible. Remember, 
the size of the records following the first record must be equal to or 
less than the size of the first record. 
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Allocation of File Space 

Previously in this section, reallocating diskette file space using the 
)FREE and )MARK commands was discussed (see Reallocating 
Diskette File Space). Using the )FREE and )MARK commands to 
reallocate diskette file space can cause fragmented blocks of 
unallocated file space on the diskette. For example, assume a diskette 
has all the file space allocated, except the following 15K of file space 
on a cylinder: 

Diskette 



Now, if you need that 15K of storage for a new file to be marked, the 
storage is not available because it is not in 15K continuous bytes. 

The fragmented blocks of unallocated file space can be made available 
by the compress function (see the IBM 5110 Customer Support 
Functions Reference Manual , SA21-9311). The compress function 
closes the gaps caused by the unallocated file space and places all of 
the unallocated file space in one continuous area. 



Chapter 9. Printer Control 


You can specify what data is sent to the printer by using the )OUTSEL 
system command or an APL shared variable. Also, at any time, you 
can print all the information on th e display screen by holding down the 
CMD key and pressing the j + j key. When an APL shared variable 

is us ed to send data to the printer, except for using the CMD 
and | 4 j key, all the data to be printed must be assigned to 

the shared variable. (See Input/Output Control for more information 
on using shared variables for printing data.) The )OUTSEL command 
has three options to specify which data on the display screen is 
printed. These options are: 


• ALL-specifies that all subsequent information displayed is printed. 


• OUT-specifies that only output is printed. Even though input is 
displayed it is not printed. For example: 


8 


5+3 


-If you enter this statement, the statement 

is displayed but not printed. 

The output (result) from the statement is displayed 
and printed. 


• OFF-specifies that none of the information displayed is printed, 
unless an APL shared variable is used to send the data to the 
printer. 

You can use the following system variable and APL function to specify 
the format of printed output: 

• DPP Specifies the printing precision of numeric data (how many 

digits are printed) 

• 5 DOC n Specifies the starting print position (tab n) from the left 

margin 

• ▼ Formats numeric data into character data 
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FORMATTING OUTPUT 


You can use the DPP system variable to specify the number of digits 
to be displayed and printed for decimal numbers and for integers with 
more than 10 digits. In a clear workspace, the DPP system variable is 
set to 5 (default value). For example: 

;| 23M-S . 67 __ A decimal number with seven digits. 

1234-6 


Only five digits are displayed, and the least significant 
digit is rounded off. 


The value of DPP does not affect the internal precision of the system. 
For example: 


A <" 1- 2 3 M- 5.6 < 
A 

1231+6 ■ 

0 P Pi-7 
A 

123 * 15.67 -- 


ITPP*-2 

A 


1. , 2E4- 


■ Only five digits are printed. 

Change the printing precision to seven digits. 
-Notice that the value of A is still seven digits. 


Even though only two digits are printed, the 
internal value of A in the system is seven digits. 


Although the DPP system variable allows you to specify the number of 
significant digits printed for decimal numbers or integers with more 
than 10 digits, there might be times when even more control is needed 
for the printed output. The T (format) function allows you to 
specify the precision and spacing of numeric data. The * function 
also converts the numeric data to character data. This makes it easier 


to print the formatted numeric data with other character data. For 

example: 


Numeric Value 

1 THE CLASS 

AVERAGE IS: 

' ,80 

DOMAIN ERROR 



'THE CLASS 

AVERAGE IS: 

‘ , 8 0 — -You cannot join numeric 



a and character data 

'THE CLASS 

AVERAGE IS: 

1 , t 8 0 

THE CLASS AVERAGE 

i 

: is: so 

-The Format Function 


The Printed Result 



The following examples show how the j function can be used to 
control spacing and precision of numeric data (see the IBM 5110 APL 
Reference Manual, SA21-9303, for a complete description of 
the v function): 


L 


B i - 3 2 p :l. 2,3 4 " 3 M , 5 67 0 1.2 " . 2 6 " 1 2 3 , 4 5 
B 

2.34 

0 1.2 |-«-Numeric Value of B 

0,26 


"34.5671 

1.2 

"1.23. i+5 J 




Spacing of Nine Positions for Each Number 


9 2 t B 
1.2,34 "34.57 

.00 12.00 

"• .26 "1.23.45 


Each number should contain two decimal places 
-Formatted Character Result 


Spacing and Precision for the First Column 


_ if Spacing and Precision for the Second Column 

P 6 2 U 9 1. i B 
1.2.34 "34.61 

. 0 0 1.2.0 I-*-Formatted Character Result 

" .26 "1.23.4J 

^- 1 _ I 


Nine Positions 


Six positions 


You can use the DCC (console control) system function to specify a 
tab position from the left margin. The printed output then starts from 
that tab position. To specify the tab position, the left argument of the 
□CC function is 5 and the right argument specifies the tab position. 
For example: 


1 PRINTED 
PRINTED OUTPUT 


20 


OUTPUT * 



The explicit result of 
the IUCC function. 


1 PRINTED OUTPUT 
PRINTED OUTPUT 


L 


J 


20 character positions 
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FORMATTING REPORTS 


Sometimes the data stored in the 5110 cannot be used unless the data 
is in a printed report. And the printed report cannot be used unless 
the report is in a readable format. The following procedure can be 
used to generate a readable report, assuming the necessary data for 
the report is already stored in the 5110: 

1. Determine the headings for the report. The headings should 
describe the information in the report. 

2. Arrange the data so that the data will be located under the 
appropriate heading. 

3. Edit the data (see Useful APL Statements and User-Defined 
Functions for Formatting Reports). 

4. Print the data. 


The following example shows how this procedure might be used. 

Assume you have the following data stored in the system: 

PART’ A numeric matrix with each row representing 

3924 01 a part number of items in stock 

392402 
392403 
392404 
392405 
392406 
392407 


NAME 

SCREW 

NUT 

WASHER 

CONTACT 

LEAD 

POST 

CRT 


A character matrix with each row representing 
the name of the associated part number in 
matrix PART 


9 0 9 

0 9 2 9 

Of DATA-- 


_A numeric matrix that 

10 0 0 

0 

, 02 

10 0 0 

contains the in-stock quantity. 

10 0 0 

0 

. 01 

1 0 0 0 

on-order quantity, cost per 

50 0 0 

20 0 0 

, 01 

20 0 0 

part, and reorder quantity for 

0 

0 

.50 

20 0 0 

the associated part number 

20 

50 0 

1 . 03 

50 0 

in matrix PART 

40 0 

0 

2.72 

50 0 


50 0 

20 0 

136.59 

20 0 
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Now, suppose you want a part inventory report that shows: 
• The part number arid name. 


• The in-stock and on-order quantities. 

• The cost per part. 

• The reorder quantity and reorder flag. The reorder flag indicates 
that the combined in-stock and on-order quantities are less than the 
reorder quantity. 


The first step is to determine the headings for the report. In this 
example, the following heading is entered: 


Position 1 on Line 1 


H E A D <-2 56 p ’ PAR T QUAN T X "f Y C 0 S T 

RDER‘NUMBER NAME IN-STOCK ON-ORDER PER PART QTY 


The second step is to arrange the data so that it is located under the 
appropriate heading. In this example, the following statements are 
used to arrange the data: 


REC) 
FLAG * 


BODY*- <6 0 t PART) , ‘ \ NAME-- 

BOB'Y<-BODY Q,9 0 , 12 2 8 Q j tDATA 


Join the part numbers and names 
together. 


This matrix now contains the 
part number, name, in-stock 
quantity, on-order quantity, 
cost per part, and reorder 
quantity for each part on 
inventory. 


“The spacing and precision to format each 
associated column of the matrix DATA. 
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At this point there is not enough information available to complete the 
report. The reorder flag is needed to indicate the parts with a 
combined in-stock and on-order quantity that is less than the reorder 
quantity. The following user-defined function might be used to place 
asterisks (*) in the reorder flag column when the in-stock plus 
on-order quantity is less than the reorder quantity: 

V REO RDE RFL AG C Q 3 V 

v rf«-reorderflag;i;x 

I*(DATAC;13+DATAC; 21 )< DATAC;M 1 
X<-\ (1 tpDATA) 

j ^ [ /X * -Selects the rows where the condition 

R| :: >( < 1 tpDATA) ,5) P ' ' specified in statement 1 is true 

rfc i 

V \ 

N Places the reorder flag (*****) in the appropriate rows 

Now, the following statement can be used to add the reorder flag the 
report data: 

BODYt-BODY, RECORDER FLAG 


The body of the report now looks like this: 


BODY 





392.401 SCREW 

1000 

0 

. 02. 

10 0 0 

392402 NUT 

1000 

0 

. 01 

100 0 

392403 WASHER 

3000 

2000 

. 01 

20 0 0 

392404 CONTACT 

0 

0 

.50 

2000***** 

392405 LEAD 

2.0 

500 

1 . 03 

50 0 

3924 06 POST 

40 0 

0 

O 7 

A» 1 I 

500***** 

392407 CRT 

50 0 

20 0 

136.59 

■ i ii f*K\ • 

200 


The third step is to edit the data. In this example, a dollar ($) is to be 


placed before each cost per part. 


C 1 1 
121 
C33 
CM-3 
C53 


bodyc:;36:k , $’ 



The fourth step is to print the report. This might be done several 
ways; for example: 

• Join the heading and the body and then print the entire report. 
REPORT*HEAD,Cl 3BODY 


• Use a user-defined function to print out the report. For example: 


VREP0RTCCI3V 

V REPORT 

Cl 3 HEAD . 

I" 2 3 BODY** < 6 0 tPART),' ‘,NAME 

C 33 BODY<-BODY , & 0 9 0 12 2 8 D fDATA 

C43 B0DY<-B0DY, REORDERFLAG 
C53 BODYC ; 363<-' $ ' 

C 63 BODY 

V 


Now, when the report is printed, it looks like this: 


REPORT 


PART 


QUANTITY 


COST 

REORDER 

NUMBER 

NAME 

IN-STOCK 

ON-ORDER 

PER PART 

QTY FLAG 

3924-01 

SCREW 

1000 

0 

$ 

. 02 

1000 

392402 

NUT 

1000 

0 

$ 

,01 

1000 

392403 

WASHER 

5000 

2000 

$ 

.01 

20 0 0 

392404 

CONTACT 

0 

0 

* 

.50 

2000 ***** 

392405 

LEAD 

20 

500 

* 

1 . 03 

500 

392406 

POST 

40 0 

0 

$ 

2 72 

500#*xw* 

392407 

CRT 

50 0 

20 0 

$ 

136.59 

200 
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USEFUL APL STATEMENTS AND USER-DEFINED FUNCTIONS FOR 
FORMATTING REPORTS 

Following are examples of APL statements and user-defined functions 
that might be useful for formatting reports. 


Drop Blanks from a Character Vector: 


VDROPCrPV 

V Z4-DR0P X 

Cl 3 Z^X?*' • )/X 

V 

X<- ‘ A B C D E FG* 
DROP X 
ABCDEFG 


Drop Blanks and Periods from a Character Vector: 

VDR0PBPCQ3V 

V Z<-DR0PBP X 

111 Z<- ( "X€ ' , 1 )/X 

V 

X<- ’ A , B . C D E F ' 

DROPBP X 

ABODEF 

Replace Periods with Commas in a Character Vector: 


V RE PLACE CQIIV 

V Z<-REPLACE X 

i::i:i xc<x«’. 1 )/xpX3<-' ,' 
1123 z*-x 

V 


x 

A.B.C D E F 

REPLACE X 
AiB,C D E F 

Drop Leading Blanks in a Character Vector: 

VLEADINGC: 03 V 
V Z<“LEADING X 

ci :i z<-(-a\' x) / x 
v 

A<-’ ABC DEF* 

LEADING A 
ABC DEF 
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Left-Justify the Names in a Matrix: 


VLJCCPV 

V Z«-LJ X 

cm z+-(+/a\x=‘ *) 0 X 

V 


NAMES*-3 6f>' SUE JAN DAVE 
NAMES 

SUE 

JAN 

DAVE 

LJ NAMES 

SUE 

JAN 

DAVE 


Find the index of a Name in a Table: 


vindexccpv 

V Z4-NAME INDEX TABLE 

ClII Z<“ (< TABLE A I a < “ 11pTABLE) f NAME)) / x 11 pTABLE 

V 


NAMES 

SUE 

JAN 

DAVE 

‘JAN’ INDEX NAMES 
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Insert Blank Lines into a Character Matrix: 


V B L A N l< LIN E S C [] J V 

V Z«-X BLANKLINES M 

i: 1 :i Z<" < < <1 1 pM > +L < 1 1 pM) *X> p < Xpl), Q > \M 

V 


DON 

DAN 

SUE 

JIM 

TOM 

KIM 

DUN 

DAN 


NAMES*-6 *+p 1 DON DAN SUE JIM TOM KIM 
NAMES 


2 BLANKLINES 


-The left argument determines how 

often the blank lines are inserted. 

NAMES 


SUE 

JIM 


TOM 

KIM 

Print a Matrix Using a Shared Variable: 

VPRINTLOIIV 

V PRINT X;Z;P 

Cl 3 C RH3 A V C [] 10+1563 

C23 P<“' PRT ' 

C33 Z*1 OSVO 'P‘ 

i:«+3 Pi-“Ur, (tX) , cr 

V 

NAMES*-3 4p 1 SUE JAN DAVE’ 
NAMES 

SUE 

JAN 

DAVE 

PRINT NAMES 

SUE 

JAN 

DAVE 



Drop Leading Blanks or More than One Consecutive Blank from a Character 
String: 

VSCANC 03 V 

V Z4-SCAN X 

ci3 Zf-uax** ■ >v •j^nm/xt-* 1 ,x 

V 


A<“* A B C D EF* 
SCAN A 
A B C D El- 


Convert a Scalar or Vector to a Matrix: 


V CON VERT C01I7 

V Z 4-CON VERT X 

1“:LII "KO 1 2 =p*>X)/<SCALAR, VECTOR, MATRIX) 

C23 MATRIX IZ4-X 
C33 *0 

CM-3 SCALAR :Z4- ;L 1 pX 
C53 K) 

C61I VECTOR :Z4- Cl., pX)pX 

V 

A 4-1 
pA 

A4-CONVERT A 
pA 

1 1 


Join Two Variables Together Side by Side: 


VBYCQ3V 

V Z4-A BY B; ROW 

Cl 3 A4-(2t ( pA) , 1 1) pA 

C23 B4-(2t<pB>, 1 1) pB 

C33 ROUf-lt <pA)|"pB 
DUI A4- ( ROU , “11 pA) t A 

C5II B<- < ROW, 11 pB) f B 

C 6 3 Z4-A>B 

V 

A 4-2 2 p 1 A ‘ 

B4-3 3p ’ B ’ 

A BY B 

AABBB 

AABBB 

BBB 
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Join Two Variables Together One on Top of the Other: 


VONtXJUV 

V Z*-A ON B j COL 
Cl 3 A<-( ~2t 1 1 ,pA)pA 

C23 B<-( “2t 1 1 , pB)pB 

t: 3 :i col.*- “it (pA)rpB 

D+3 A*- < < 11 pA >, COL) t A 

11511 B*< (ItpB) , COL) tB 

i:6n z<-a, im b 

v 

A<-2 2 p ' A ' 

B*-3 3 p ’ B ' 

A ON B 
AA 
AA 
BBB 
BBB 
BBB 
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Chapter 10. Input/Output Control 


Input/output operations consist of the following: 

• Reading and writing data records on a tape or diskette data file 

• Reading and writing data on the display screen 

• Printing data records 

In this chapter, the following topics concerning input/output control 
are discussed: 

• Sequential and direct access data files 

• Logical and physical records 

• Types of data file formats 

• APL internal code to EBCDIC (extended binary coded decimal 
interchange code) translation 

• The 5110 I/O processor 

• Establishing an APL shared variable as the connection between the 
active workspace and the I/O processor 

• Using the APL shared variable for input/output operations 

• Retracting the shared variable offer 
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SEQUENTIAL AND DIRECT ACCESS DATA FILES 


Sequential access data files can be on tape or diskette: however, 
direct access data files can only be on diskette. The data file is 
specified as either a sequential access or direct access data file when 
it is initially created (see Specifying the Operation to be Performed 
later in this chapter). 


All 5110 data files are created sequentially: that is, individual records 
are written to the file in sequential order. 


Data File 


Record 1 

Record 2 

Record 3 

Record 4 

Record 5 


After a data file is created, data can be read from the file as follows: 

• For a sequential access file, the records are read in the same 
sequence as the records were written to the file. For example, the 
first and second record must be read before the third record can be 
read. Also, if you want to read a record previous to the last record 
read, you must start the operation over from the beginning of the 
data file. 

• For a direct access data file, you specify the record(s) that are to be 
read from the data file. For example, you can specify that the fourth 
record in the file be read {without reading the previous three 
records) then after the fourth record is read you can specify that the 
second record in the file be read, and so on. Also, multiple records 
can be read with one statement. 


LOGICAL AND PHYSICAL RECORDS 

A logical record is the individual record written to a data file. For 
sequential access data files, the size of each logical record can vary. 
For example, one logical record might require 10 bytes of storage and 
the next logical record might require 20 bytes of storage. For direct 
access data files, each logical record requires the same amount of 
diskette storage. Generally, each logical record must be the same 
shape and representation as the other logical records in the data file. 

A physical record is a certain amount of tape or diskette storage. For 
tape, a physical record is 512 bytes. For diskette, a physical record is 
the same as the diskette sector size (128, 256, 512, or 1024 bytes). 



TYPES OF DATA FILE FORMATS 

For Sequential Access Data Files 

There are two types of data file formats for sequential access data 
files: 

• APL internal format 

• General exchange format 

Following is a description of these data file formats. 


APL Internal Format 

The APL internal format allows data to be written to the data file in 
the same format as that stored in the active workspace. For example, 
the first record written to the data file might be a numeric 10 x 20 
matrix, and the second record written to the data file might be a 
10-element character vector. 


General Exchange Format 

The general exchange data format is the basis of exchange between 
the 5110 APL and BASIC languages. The general exchange format 
only allows character scalars or vectors to be written to the data file. 
Therefore, when the system is storing numeric data in data files with 
the general exchange data format, the format function must first be 
used to change the data to a character scalar or vector. 

The following rules apply to a general exchange format data file that is 
written using the APL language for later processing using the BASIC 
language. 

1. All data items must be separated by commas. For example, the 
numeric vector 1 3 5 6 must be changed to character data, then 
commas must be placed in the blank positions. The following 
statement replaces blanks with commas in a character vector: 

X L(X™' ) / \ pX _l - where X is the character vector. 

2. Negative signs must be replaced by minus signs. 

3. The 5110 BASIC language accepts only the first 255 characters in 
each character constant. 

4. The 5110 BASIC language creates a logical record for each PUT 
statement or each row of an array with a MAT PUT statement. 
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When the 5110 APL language is used to read a general exchange 
format data file (see To Read a Sequential Access Data File later in 
this chapter), the following actions are taken by the 5110 if a cursor 
return character (hex 9C) or end-of-block character (hex FF) was 
embedded in a character vector that was written to the data file: 

e If a cursor return character was embedded in the character vector, 
the data will be read from tape in a different sequence than it was 
written to tape. This condition occurs because as the interchange 
data is written to tape, the system writes an end-of-record 
character (hex 9C) after each character vector (record) that was 
written to tape. The end-of-record character and the cursor return 
character are the same. When used on tape, this character 
separates the data (records) so that it can be read from tape in the 
same sequence as it was written to tape. However, if a cursor 
return character is embedded in the data that was written to tape, 
the system will recognize it as an end-of-record character when the 
data is read from tape. 

o If an end-of-block character was embedded in the character vector, 
any data from the embedded end-of-block character to the next 
physical record is not read from tape. This condition occurs 
because the system looks at the tape in 512-byte segments (one 
physical record). A physical record can be terminated by an 
end-of-block character (hex FF). When the system is reading data 
from the tape and an end-of-block character is encountered, the 
system skips to the next physical record and continues reading data. 
Therefore, if an hex FF character is embedded in the data that was 
written to tape, the system recognizes it as an end-of-block 
character when the data is read from tape and skips ahead to the 
next physical record. 


For Direct Access Data Files 

There are five types of data file formats for direct access data files. 
These formats are: 

» APL internal format 

« General exchange format 

» Unblocked and unspanned format 

• Mixed format 

® Nontranslated format 


Following is a description of these data file formats. 



APL Internal Format 


The APL internal format allows data to be written to the data file in 
the same format as that stored in the active workspace. However, 
unlike sequential access data files, all the records written to the data 
file must have the same shape and internal representation. For 
example, all of the records written to the data file must be one of the 
following: 

• Character data 

• Numeric binary data (all zeros and ones) 

• Numeric fixed point (all integers in the range -2 31 to 2 31 -1) 

• Numeric floating point (all other values) 

These records must have the same shape and representation because, 
when multiple records are read from a direct access data file, the 
records are laminated (joined) together along a new first dimension 
(see Updating a Direct Access Data File later in this chapter). 


General Exchange Format 

The general exchange format for direct access data files is similar to 
the general exchange format for sequential access data files (see For 
Sequential Access Data Files under Types of Data File Formats in this 
chapter). However, when the general exchange format is used with 
direct access data files, all the records written to the data file must be 
character data and must have the same shape (p DATA) as the first 
record written to the data file. The records must have the same shape 
because, when multiple records are read from a direct access data file, 
the records are laminated together along a new first dimension. 
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Unblocked and Unspanned Format 


The unblocked and unspanned format is the basis for general 
exchange with other products using diskette storage. In this case, the 
file name cannot exceed 8 alphameric characters, and the diskette 
sector size must be 128 or 256 bytes. 

The unblocked unspanned format allows only character scalars or 
vectors to be written to the data file, with each record starting on a 
sector boundary. Also, the records cannot exceed (span) a sector 
boundary. 


Sector Boundaries 



When the unblocked and unspanned format is used, all the records 
written to the data file must have the same shape (p DATA) as the 
first record written to the data file. The records must have the same 
shape because, when multiple records are read from a direct access 
data file, the records are laminated together along a new first 
dimension. 

Since the unblocked unspanned format requires each record to start 
on a sector boundary, to prevent wasted diskette storage the record 
size should be as close as possible to the sector size. The unused 
diskette storage in each sector is unavailable for storing data (see 
Type U Data File in Chapter 8, Diskette Concepts). 



Mixed Format 


The mixed format, like the APL internal format, allows data to be 
written to the data file in the same format as the data is stored in the 
active workspace. However, the mixed format also allows you to 
write records that have different internal representations on the same 
data file. For example, you can write character data, logical data, 
numeric fixed-point data, and numeric floating-point data on the same 
data file. With the mixed format, the first record written to the data 
file determines how much file storage is allocated for each additional 
record to be written to the data file. For example: 



If the first record requires 100 bytes of file storage, 100 bytes of 
storage are allocated for each additional record. See Storage 
Requirements in the 5110 APL Reference Manual for information on 
how many bytes of storage are required for each data type. 

As various size records are written to a mixed format data file, any 
unused diskette storage allocated for each record is unavailable for 
storing data (see Type M Data File in Chapter 8, Diskette Concepts). 

Because the records in a mixed format data file do not have to be the 
same shape or internal representation, only one record at a time can 
be directly accessed from the data file. That is, multiple records 
cannot be laminated together. 
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Nontranslated Format 


The nontranslated format is used primarily for reading diskettes from a 
non-5110 system and the diskette does not have standard 5110 file 
types. Therefore, unless you need to read diskettes that do not have 
standard 5110 file types, you might want to skip this topic. 

The nontranslated format is the only format that is not specified when 
the data file is initially created. The nontranslated format can be 
specified only when the system is reading from or writing to any 
diskette data file that already exists. When data is written to a direct 
access data file using the general exchange or unblocked unspanned 
format, the APL internal code is translated to EBCDIC code before the 
data is written on the diskette. This EBCDIC code is then translated 
back into the APL internal code when the data is read back into the 
active workspace. 




Js. 

.OEz!Z 

APL Internal Code 

> EBCDIC Code ^ 

„ r Tl 1 U 

^ APL Internal Code 

EBCDIC Code m 




1 


Active Workspace Translation Diskette Storage 

Tables 


However, when the nontranslate format is specified, all attributes of 
the file are ignored and any existing diskette file can be read from or 
written to. In this case, as the data is being read from or written to 
the file, the data is not translated from the EBCDIC or APL internal 
code to the other code. 

Instead, as data is being read in the nontranslate format from an 
EBCDIC diskette file, the EBCDIC representation of the data is placed 
in the active workspace. Or when data is being written in the 
nontranslate format to the diskette file, the APL internal representation 
of the data is written to the diskette file. 



Note: Assuming DIO is 0, the APL internal representation of a 
character is equivalent to the hexadecimal value of that character's 
index in the atomic vector. For example, the APL internal 
representation of the character A (DAV [86]) is hex 56 (the bit value is 
01010110). You can determine the bit value of the atomic vector index 
using the encode (t) function. For example: 


9 

A*» 

p 1 0 .1, 


2 2 2 2 

p 1 1 0, 


'■> '■> 


r 86 



Hexadecimal 56 


The EBCDIC character A has a hexadecimal value of Cl or a decimal 
value of 193. In non-translate mode (and DIO^-1), when the EBCDIC 
character A is read from a diskette, the character is stored internally 
and displayed as a lowercase h (DAV [193]). 

The nontranslate format allows only character vectors to be written to 
the file. Also, each sector on the diskette is considered one record. 
Therefore, if you specify that three records should be read or written, 
you will read or write three sectors on the file. 


Sector Boundaries 



When nontranslate format is used, 
three records are equal to three sectors. 
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THE 5110 I/O PROCESSOR AND SHARED VARIABLES 


The 5110 I/O processor is responsible for transferring data from the 
active workspace to the tape, the diskette, the display screen, or the 
printer, and for transferring data from the tape, the diskette, or the 
display screen to the active workspace. Before individual data records 
can be transferred by the I/O processor, a shared variable must be 
established as the connection between the active workspace and the 
I/O processor. That is, the variable is shared between the active 
workspace and the I/O processor. 

Once this connection is established, the shared variable is used to 
send control information and data to the I/O processor and to receive 
return codes and data from the I/O processor. 



ESTABLISHING AN APL SHARED VARIABLE 


A variable must be offered to the I/O processor before the variable 
can become a shared variable. To do this, you must use the DSVO 
(shared variable offer) system function. The DSVO function requires 
two arguments; the left argument must be 1 (to specify the 5110 I/O 
processor), and the right argument must be character data that 
represents the variable name(s) to be shared. If more than one name 
is required, the names may be entered as a character matrix with each 
row representing an individual name. For example: 

X OB VO 1 A ' --—The variable name A is 

offered to be shared. 


1 0SV0 3 1 (>' ABC * 

The variable names A, B, and C are 
offered to be shared. 

The DSVO function generates an explicit result of 2 for each variable 
name that is successfully established as a shared variable with the I/O 
processor. For example: 

□SVG 3 lp*ABC* 


There are two users of the shared variable, the 
active workspace and the I/O processor. This is called 
the degree of coupling. 

A 0 or 1 is the result of the DSVO function for each variable name that 
is not successfully shared with the I/O processor. If the result is 1, 
the left argument of the OSVO function was a value other than 1. In 
this case, the variable name must be retracted and offered as a shared 
variable again with a 1 as the left argument of the DSVO function 
(retracting the shared variable name is discussed later in this chapter). 

If the result is 0, an error message is also displayed. 

You can establish up to 12 shared variables in the 5110 active 
workspace. If you attempt to establish more than 12 variable names 
as shared variables, the error message INTERFACE QUOTA 
EXHAUSTED is displayed. The statement ( O^OBVO ONL 2)/[]NL 2 
displays the existing shared variable names in the active workspace. If 
12 shared variable names are already established, you must retract a 
shared variable name before another variable name can be offered. 
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USING APL SHARED VARIABLES 


Once a shared variable is established as the connection between the 
active workspace and the I/O processor, you can do the following 
input and output operations: 

• Create a new sequential access or direct access data file. 

• Add data to an existing data file. 

• Read data from a sequential access data file. 

• Read-only data from a direct access data file. 

o Update (read and write) data in a direct access data file. 

• Read data from and write data to the display screen. 

« Send data to the printer. 

The first value assigned to the shared variable must be a character 
string (enclosed in single quotes) that specifies the operation to be 
performed. Specifying the operations to be performed and doing 
input/output operations are discussed next. 



To Create a New Sequential Access or Direct Access Data File 

The first value assigned to the shared variable must specify the 
operation to be performed as follows: 


SV 


OUT 

'OUTF 


device/file number ID = (file ID) MSG = OFF TYPE = | 


Type of data file: 

• OUT — Sequential access 

• OUTF — Direct access 


Direct access 
files only 


U 

M 


Type of data file format: 

•A — APL internal 
I — General exchange 

Unblocked/unspanned 
M — Mixed 


• i 

(• u 

^ • M 


For example: 


SVf-’OUTF 110 


03 ID-"(SALES) MSG*OFF TYPE«U' 

t 


Unblocked and unspanned 
data file format. 


The error messages are not displayed. 
The data file identification is SALES. 


Diskette drive 1, file 3. 
Create a direct access data file. 


(See the IBM 5110 APL Reference Manual for a detailed description of 
each parameter.) 
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Once the operation to be performed is specified to the I/O processor, 
the I/O processor assigns a return code to the shared variable. For 
example: 


0 0 


SV< -' OUTF 11003 ID™ (SALES) MSG-OFF TYPE-U* 
SV-*-~The return code is checked by referencing the 



shared variable. 

The return code is a two-element vector. 


In the previous example, the return code is 0 0, which indicates that 
the operation to be performed is successfully specified to the I/O 
processor. See the IBM 5110 APL Reference Manual for a description 
of all the return codes. 


Once the operation to be performed is successfully specified, the 
shared variable used to specify the operation is then used to specify 
data that is to be written on the data file. That is, each time new data 
is assigned to the shared variable, the I/O processor transfers that 
data to a data file and assigns a return code to the shared variable. 

For example: 

Remember, in this example, the 
data file format is unblocked and 
unspanned. All of the records in the 
data file must have the same shape. 


b v „....—-Notice that the shared variable 

10 STATUS: INVALID OPERATION cannot be referenced more than 
INTERRUPT once to check the return code. 

SV 


8V*12t'RECORD ONE* 
SV 

0 0 

SV<12t* RECORD TWO* 
SV 

0 0 


0 

0 


SV<-12t 1 RECORD THREE' 

X«-SV 

X 

^ — -——The return code can be assigned to another 

----- variable and then checked more than once. 



When ail of the data is written to the data file, the operation must be 
terminated. The operation can be terminated by assigning an empty 
vector to the shared variable. For example: 

S Vt 0 --Empty vector 

sv 

^ ^ The operation is terminated. The variable 

SV is still shared with the I/O processor. 

Therefore, SV can be used to specify and 
perform another input/output operation. 

See the IBM 5110 APL Reference Manual for a description of other 
ways to terminate the operation. 


To Add Data to an Existing Data File 

There will be times when you want to add data to an existing data file. 
If you specify an OUT or OUTF operation, the data you write to the 
file always starts at the beginning of the file and the new data is 
written over any existing data. Therefore, to add data to a data file 
starting after the last record in the file, you must specify the operation 
to be performed as follows: 

SV «- 'ADD [device/file number] [ID = (file ID)] [MSG = OFF]' 
For example: 


0 0 


SV< * ADD 11003 ID«<SA 
SV 


.ES> MSG™OF 


| Do not display the error messages. 

The file identification of the existing data file. 
The data file is on diskette drivel, file 3. 

Add data starting after the last record in the data file. 


Even though the device/file number and ID = (file ID) parameters are 
optional, one or the other of these parameters must always be 
specified. 
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The type of data file (sequential access or direct access) and data file 
format are determined by the attributes of the existing data file. In this 
case, assume this example is continued from the previous topic, the 
file is a direct access, unblocked, and unspanned data file. 

Once operation is specified, data can be sequentially written to the 
data file. For example: 

SV*12t’RECORD FOUR* 

SV 

0 0 

SV«-12t • RECORD FIVE* 

SV 

0 0 

SV*- X (H-You can terminate the operation 

SV by assigning an empty vector to the 

0 0 shared variable. 


To Read a Sequential Access Data File 

Once a sequential access file is created, the records are sequentially 
read from the data file. That is, the records are read from the data file 
in the same sequence as the records were written to the data file. 

You specify the operation to be performed as follows: 

SV«- 'IN [device/file number] [ID = (file ID)] [MSG = OFF]' 

For example: 


0 0 


SV*- ’ IN 1 :l. 0 0 M I D= (SEQ) MSG "OF F * 

SV t t t t 


Do not display the error messages. 
The existing data file identification. 

The data file is on diskette drive 1, file 4. 

Read data from a sequential access data file. 



After the operation is specified, the I/O processor assigns a return 
code to the shared variable. The I/O processor then assigns a new 
record from the data file to the shared variable each time the shared 
variable is referenced. For example: First, to create a sequential 
access file with 5 records. 

1 OSVO 'SV 1 

VSEQUENTIAUTPV 

V SEQUENTIAL. 

i::i::i sv<- • out no on- id=<seq> type=a* 

123 I <-l 

C33 LOOP : (v/Q^X«-SV) /ERROR 

i:m::i sv<-* record * ,ti 

C53 -K5> inn )/loop 

163 SV** x 0 

i:: 73 ■*<A/o«Xf-sv)/o 

\ ; &3 ERROR: ’CREATING THE DATA FILE FAILED. THE RETURN CODE IS: 

, f X 

V 


SEQUENTIAL 


Now, to read the 5 records from the data file. 


You should check the return code after the 
operation is specified. 

After the return code is checked, each time 
the shared variable is referenced, the I/O 
processor assigns the next record from the 
data file to the shared variable. 

If you want to save a record for later use, you 
must assign the shared variable to another variable. 


After the last record is read from the file, an empty 
vector (sO) is assigned to the shared variable. This 
empty vector terminates the operation. (In a 
user-defined function, you can check for the 
empty vector. For example: -> (0 = pX SV)/DONE. 
The statement branches to DONE if the last record 
read was an empty vector.) 


SV<-' IN ID"“(SEQ) ' 
SV-*-- 

0 0 

SV 

RECORD I 
SV 

RECORD 2 
SV 

RECORD 3 

x<-sv 

X 

RECORD '! 

SV 

RECORD 5 
SV 


0 0 
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When reading a sequential access data file, the I/O processor does 
not assign return codes to the shared variable. However, if an error 
occurs, an empty vector is assigned to the shared variable and the 
operation is terminated. Then the I/O processor assigns a return code 
to the shared variable that indicates why the error occurred. 

You can also terminate the operation at any time by assigning an 
empty vector to the shared variable. For example: 

SV«-'IN ID=(SEQ)’ 

SV 

0 0 

SV 

RECORD 1 
SV 

RECORD 2 

cjy*. x () ^-The read operation is terminated. 

SV — 

0 0 


To Update Data in a Direct Access Data File 

Once a direct access data file is created, specified records in the data 
file can be updated. That is, records can be read from the data file, 
updated in the active workspace, and then written back to the data file 
at a specified record location. Unlike the operations discussed so far, 
reading or writing specified records on a direct access data file 
requires a pair of shared variables. One of the shared variables is 
used to specify control information to the I/O processor. The I/O 
processor also assigns the return codes to this shared variable. The 
other shared variable is used for data that is written to or received 
from the data file. The pair of shared variable names must have the 
following characteristics: 

• The shared variable name used to specify the control information 
must have the 3-character prefix CTL. 

• The shared variable name used for the data must have the 
3-character prefix DAT. 

• After the 3-character prefix, the next 15 characters in each name 
must be identical, if specified. For example: 

These variable names can be used as 
a pair of shared variables. 




Once the pair of shared variables is established, you specify the 
operation to be performed as follows: 


CTL <- 'IOR [device/file number] [ID = (file ID)] [MSG = OFF] [TYPE = N1' 
IORH ♦ 


Read or write to a 
direct access data file. 

See the IBM 5110 APL 
Reference Manual for 
a description of the 
differences between an 
IOR and IORH operation. 


If this parameter is 
specified, the data is 
not translated (see 
Nontrans/ated Format). 

The other formats cannot be 
specified when you are 
reading from or writing to a 
direct access data file, because 
these formats were established 
when the file was created. 


For example: 


0 


CTL<-' IOR 
CTL f 


110 0 3 I D« ( D I RE CT) MSG«OFF * 


I Do not display the error messages. 

The file identification. 

The data is on diskette drive 1, file 5. 

Read records from or write records to a direct access data file. 

For a read or write operation to a direct access data file, the second 
element of the return code identifies the number of records in the data file. 
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After the operation is specified, the CTL shared variable is then used 
to specify what records to read or write. To do this, you must assign 
a two- or three-element vector to the CTL shared variable, as follows: 

0 

CTL *- 1 starting record number [number of records] 

2 

/ 

^—0 specifies a read records operation. If the third element 

1 specifies a write records operation. is not specified, one 

2 specifies a search by key operation. record is assumed. 

(search by key is discussed 

later in this section). 


For example: 


CTL.*\0 5 3. 


-Read three consecutive records, starting with 
the sixth record in the file. 


Note: The record numbering starts with zero. 



Therefore, the first record in the file is record number 0, the second is 
record number 1, and so on. Also, you cannot read from or write to a 
record position that was not originally created using an OUTF or ADD 
operation. 


When the CTL shared variable specifies a read records operation, the 
I/O processor assigns the records read from the data file to the DAT 
shared variable. When the CTL shared variable specifies a write 
records operation, the data currently assigned to the DAT shared 
variable is written to the data file. Therefore, the data must be 
assigned to the DAT shared variable before you specify the write 
operation. In each case, after reading or writing records, the I/O 
processor assigns a return code to the CTL shared variable. 
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When you read multiple records from a direct access data file, the 
records are laminated together along a new first dimension before 
they are assigned to the DAT shared variable. For example, assume 
you read three records (character vectors) from the following data file: 


DATA 

FILE 


0 

1 

2 

3 

4 

5 t 

ABCEF 

GHIJK 

DAN.. 

-:— 

DAVE. 

1 - 

JERRY 

1 - 

U 


CTL*0 2 3 
CTL 

0 0 

DAT 

DAN . . ---- 

DAVE. ------ 

JERRY __ 

pDAT 

3 5 ___—-—-The shared variable DAT contains 

a 3 x 5 character matrix. 


The new first dimension represents the number of records read. You 
can specify each individual record by indexing the new dimension. 


DATCl;3 

DAN. . 

date: 3; :i 

JERRY 
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When you write multiple records to a direct access data file, the 
records must be joined along a new first dimension before they are 
assigned to the DAT shared variable. For example, assume you want 
to write the following three records (character vectors) to a direct 
access data file: 
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Following is an example of updating records in a direct access data 
file: 

1 I.3SVQ *•* M- p Cl LXDA I X ' -— Establish a pair of 

*7 0 . . 

*- shared variables. 


i: i ::i 
£21 
C33 


VDIRECTCD3V 

7 DIRECT ; I ' X--—- Create a direct access data file. 

CTLX<- * OUTF 11004 ID-(DIRECT) TYPE-I ’ 

■*< 0^1 fXf-CTLX) /ERROR 

3! 1 CTLA and DATA can be 


i:4!3 

C53 

£61 

£71 

£B1 

£91 

£ 0)1 

cm 


LOOP : CTLXf- 1 RECORD 1 , t I used for an V >"Put/output 

-H Oi^lf Xf-CTLX)/ERROR operation. 

■> (5> II +1) /LOOP 

CTLX*- t 0 ------' This operation is terminated; 

( 0*ltX<-CTLX)/ERR0R now ^ b A can be used for other 

0 operations. 


ERROR 
* THE 


‘CREATING THE DATA FILE FAILED. 1 
RETURN CODE IS: \ fX 


DIRECT 
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The data file now looks like this: 


0 

1 

2 

3 

4 

RECORD 1 

RECORD 2 

RECORD 3 

RECORD 4 

RECORD 5 


CTLX<-' IOR 11O0M- ID®(DIRECT) ‘ 
CTL.X 


CTLX<-0 0 
CTL..X 


0 0 

DATX 
RECORD 1 



DATX*’RECORD Ai 
CTL.X<“1 0- 
CTLX 


When you specify the operation to a direct 
access data file, the second element of 
the return code is the number of 
records in the file. 

Data records can be 
read, 

updated, and 

written back at the same record location. 


0 0 


0 0 


CTLX<~0 

CTLX 

DATX 
o 


RECORD 
RECORD 3 

' CJLXi-1 3 2- 
CTLX 

0 0 


CTLX<-1 2- 
CTLX 


0 0 


RECORD A 

RECORD 2 

RECORD 3 

RECORD 4 

RECORD 5 

> 

0 

Data records can be moved from 
one record location to another 
record location. 

1 2 3 

4 

RECORD A 

RECORD 2 

RECORD 3 

RECORD 2 

RECORD 3 


■ New records can replace existing records 
in the data file. 

12 3 4 

0 

RECORD A 

RECORD 2 

NEW DATA 

RECORD 2 

RECORD 3 


0 0 


CTLX*- \ 0 
CTLX 


Remember, when you write records to the 
data file, the records must meet the 
requirements of the data file. 


Terminate the operation. Now CTLX and 
DATX can be used for other input/output 
operations. 







To Search by Key a Direct Access Data File 

When doing update operations to a direct access data file, you can 
search the file for a specific record by first assigning a key value to 
the DAT shared variable and then assigning the following vector to the 
CTL shared variable: 


CTL <- 2 starting record number of records 


Specifies a search 
by key. 


Unlike reading from and writing to 
a direct access data file, the third 
element must be specified for 
a search by key. 


When a search by key is specified, the key value currently assigned to 
DAT is checked against the equivalent number of beginning bytes in 
the specified sectors. The specified sectors include the sector that 
contains the starting record number through the sector that contains 
the last record specified (determined by the number of records 
specified). For example: 


Sector Boundaries 



When you are creating a file for search by key operations, the file 
should meet the following requirements: 

• The records are sorted in ascending sequence. 

• The records do not span sector boundaries. However, there can be 
multiple records in a sector. 


• A record that is greater than any key value that might be specified 
should start on the sector boundary following the last valid data 
record. 
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See the IBM 5110 APL Reference Manual for a description of when a 
search by key is complete. If the search is successful, the record(s) in 
the sector containing the appropriate record is assigned to the DAT 
shared variable (multiple records are laminated together along a new 
first dimension). Also, the second element of the return code assigned 
to the CTL shared variable represents the record number of the first 
record assigned to the DAT shared variable. 


0 '* 


CTL 


-The search was successful, and the first record assigned 
to DAT is record number 4. 


To Read-Only Data from a Direct Access Data File 


To read-only data from a direct access data file is the same as reading 
records when updating data in a direct access data file. However, 
when you specify a read-only operation, you cannot write data back to 
the data file (a CTL DOMAIN ERROR is generated); this prevents data 
from accidently being written to the data file. You specify the 
read-only operation as follows: 


CTL 'INR [device/file number] [ID = (file 


ID)] [MSG = OFF] [TYPE = N]' 


Read-only data from 
a direct access data file. 



For example: 



CTL 

CTL 


:i:nr 11005 id=<direct) 


MSG=OFF 1 


J Do not display the error messages. 

The file identification. 

The data is on diskette drive 1, file 5. 

Read-only data from a direct access data file. 


The second element of the return code identifies the number of 
records in the data file. 


See To Update a Direct Access Data File for a description of how 
records are read from a direct access data file. 


To Read Data from and Write Data to the Display Screen 

Reading and writing data on the display screen is similar to reading 
and writing data on a direct access data file. That is, the operation 
requires a pair of shared variables, with one of the shared variables 
having the prefix CTL and the other having the prefix DAT. You 
specify the operation as follows: 

CTL** DISPLAY CMSG«0FF3* 


The error messages are not displayed. 

Read or write data on the display screen. 

A pair of shared variables is used for reading and writing 
data to the display screen. 


Once the operation is specified, the CTL shared variable is used to 
specify what character positions to read or write. To do this you must 
assign a two- or three-element vector to the CTL shared variable, as 
follows: 


CTL 



starting character number [number of characters] 

If this element is not 
0 specifies a read data operation. specified, one character 

1 specifies a write data operation. is assumed. 
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Note: Each character position on the display screen is considered one 
record. The character positions are numbered as follows: 


LINE 



15 

0 - 

-63 

14 

64 - 

- 127 

13 

128 

- 191 

12 

192 - 

- 255 

11 

256 - 

-319 

10 

320 - 

- 383 

9 

384 - 

- 447 

8 

448 - 

- 511 

7 

512 - 

- 575 

6 

576 - 

- 639 

5 

640 - 

- 703 

4 

704 - 

- 767 

3 

768 - 

- 831 

2 

832 - 

- 895 

1 

896 - 

- 959 

0 

960 - 

- 1023 


For example: 


0TL<- 0 2 0 1. 0-*-Read 10 characters starting 

with character position 20. 


When the CTL shared variable specifies that characters be read, the 
cursor appears on the display screen at the character position 
specified by the starting character number. You can then modify the 
information on the display screen for the specified number of 
character positions. Also, the insert, delete, and ATTN key perform 
the same functions within the specified number of character positions 
as they do during standard APL keyboard input. Then, when the 
EXECUTE key is pressed, the specified characters are read from the 
display screen and assigned to the DAT shared variable as a character 
vector. 

When the CTL shared variable specifies that characters be written, the 
data currently assigned to the DAT shared variable is written to the 
specified positions on the display screen. DAT must be a character 
vector with at least as many characters as specified by the CTL shared 
variable. 




In each case, after reading or writing records on the display screen, 
the I/O processor assigns a return code to the CTL shared variable. 

Following is an example of reading and writing data on the display 
screen: 

1 OSVO 2 7p , CTLDISPDATDISP , 

'? 2 


CTLDISP*- ‘ DISPLAY * 
CTLDISP 


ctldisp*- o 6«+ 6H 

CTLDISP 

0 0 

pDATDISP 

6M- 

DAT'D ISP 
DISPLAY I/O 


DA T D .1. S P*•10 2*! P DA I D .1. S P"* After the data is assigned to 

the DAT shared variable, the 
DAT shared variable can be used 
like any other variable. 

CTLDISP*-1 0 1024- 

Write the value currently assigned 
to DAT on the display screen. 
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The display screen now looks like this: 


DISPLAY 

I/O 

d:i: 

s 

PLAY 

I/O 

DI 

S 

PLAY 

I/O 

DI 

S 

PLAY 

I/O 

DI 

s 

PLAY 

I/O 

DI 

s 

PLAY 

I/O 

DI 

s 

PLAY 

I/O 

DI 

s 

PLAY 

I/O 

DI 

s 

PLAY 

I/O 

DI 

s 

PLAY 

I/O 

DI 

s 

PLAY 

I/O 

DI 

s 

PLAY 

I/O 

DI 

s 

PLAY 

I/O 

DI 

s 

PLAY 

I/O 

DI 

s 

PLAY 

I/O 

DI 

s 

PLAY 

I/O 


Now, scroll up 2 lines 
and enter 


CTLDISP<-\0 

CTLDISP 

0 0 


to terminate the operation. 



To Send Data to the Printer 


You can control what information is printed by using an APL shared 
variable. You specify the operation as follows: 

SV«- 'PRT [MSG = OFF]' 

+ 

The shared variable is used for printing data. 

For example (assume SV is already established as a shared variable): 

SVc- 1 PRT MSG=QFF 1 
SV 

0 0 

Once the operation is specified, only the information (a character 
scalar or vector) assigned to the shared variable is printed. The I/O 
processor assigns a return code to the shared variable after each print 
operation. For example: 

S V c •• ■ 0 N L Y T H E D A T A A S 8IG N E D ’ 

SV 

0 0 

SV< - 1 JO THE SHARED VARIABLE IS PRINTED’ 
SV 

0 0 

When using a shared variable for print operations, you can only assign 
character scalars or vectors to the shared variable. However, you can 
also print a matrix as follows: 


12 

34 

56 

78 


D 0 

0 0 


M A T RI X c •• 4 2 p ' 123 4 5678 * 
MATRIX 



CRc-OAVi: 137 ] 

SVKT.I, CtMATRIX) ,CR. 

SV ‘--- 1 


Carriage return character (assuming □IO<-1). 


This expression catenates a carriage 
return character at the end of each 
row of the matrix and then ravels 
the matrix into a vector, as follows: 


SVC -1 0 

svt 


Terminate the 
operation. 


1 2 CR 3 4 CR 5 6 CR 7 8 <- The last 

CR is dropped. 

Now, when the vector is printed, 
a new line is started each time 
the carriage return is encountered, 
as follows: 


1 2 
34 
56 
7 8 


Input/Output Control 137 



TERMINATING THE OPERATION AND RETRACTING THE SHARED 
VARIABLE OFFER 


As discussed previously, you can terminate an input/output operation 
by assigning an empty vector to the appropriate shared variable. After 
you terminate the operation, the I/O processor assigns a return code 
to the shared variable, and then the shared variable can be used to 
specify another input/output operation. 

See the IBM 5110 APL Reference Manual for more information on 
assigning an empty vector to the shared variable. 

There are four other ways that you can terminate the operation: 

« Use the DSVR system function to retract the shared variable offer. 

o Use the DEX system function to expunge the shared variable name. 

o Complete execution of a user-defined function in which the shared 
variable is made local to that function. 

o Use the )ERASE system command to erase the shared variable 
name. 


In each case, the operation is terminated and the shared variable offer 
is retracted. However, a return code is not assigned to the shared 
variable to indicate whether or not the operation was terminated 
successfully. 


Generally, the DSVR function is used after the operation is terminated 
and the shared variable is no longer required for any input/output 
operations. The DSVR system function requires one argument; this 
argument must be character data that represents the shared variable 
names being retracted. If more than one name is required, the names 
may be entered as a character matrix with each row representing an 
individual name. For example: 


DSVR 'A * 


The variable name A is no 
longer a shared variable. 


DSVR 3 lp'ABC* 


/The variable names A, B, and C are no 
longer shared variables. 


The DSVR function generates an explicit result of 2 for each shared 
variable offer with the I/O processor that is successfully retracted. For 
example: 


XH3SVR 3 1 p ' ABC ’ 
X 


In this case A, B, and C 
are shared variables. 



Once the DSVR function is used to retract a shared variable offer, the 
shared variable becomes an ordinary variable. 


At-3+4- 

A 


The following chart summarizes the data file types for input/output 
operations. Sequentially accessed data files require one shared 
variable, and directly accessed data files require a pair of shared 
variables (CTL/DAT). Records in the data files can be blocked and 
spanned or unblocked and unspanned. Blocked and spanned records 
can span sector boundaries. Unblocked and unspanned records cannot 
span sector boundaries; that is, the record must be less than or equal 
to the sector size and there is only one record per sector. 


TYPE- 

Parameter and 

Data Format 

File Type 

Displayed Using 
the )LIB Command 

Comments 

Sequential Direct 
(OUT) (OUTF) 

A 

APL internal 
blocked/spanned 

8 10 

• The 5110 defaults to TYPE=A if the parameter is not 
specified. 

• For file type 10, all the records in the file must be the same 
size and representation (character, binary, fixed point, or 
floating point). 

1 

Character data 
blocked/spanned 

2 9 

• File types 2 and 9 can be read sequentially using an IN 
operation. 

• File type 9 (blocked and spanned) uses less storage than 
file type 10 for character data. 

• For file type 9, all the records in the file must be the same 
size. 

U 

Character data 

unblocked/ 

unspanned 

9 or B9 

• File types 9 and B9 can be read sequentially using an IN 
operation. 

• File type B9 is the basis of exchange with other products. 

• All the records in the file must be the same size. 

M 

APL internal 
blocked/spanned 

8 15 

• For file type 15, all the records in the file must use the 
same or less storage than the first record written to the file, 
and records must be read or written one at a time. 
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SAMPLE INPUT/OUTPUT OPERATIONS 


** SEQUENTIAL I/O ** 


S e q u e n t i a l f i l e s on cl i sk e t t e a re ess e n tia l l y t h e 
a s l' a p o f i l e s . T h e t w o t y p e s a r e I 

GENERAL EXCHANGE (File type 2) 

APL INTERNAL (File type 8) 

Sequential files req uir e only one share d m ar i ab l 


1 QSVO * SEQDSK 

9 


Th i s e x amp l e sp e c: i f i e s ' OUT ’ to i n cl i cat e o u. t p u t 
a n cl cl e f a u 11 s t o t h e A P L I N T E R N A L F i l e T y p e . 

SEQDSK 1 OUT 1 1 0 0 3. I D* (TEST) 1 

0 n c e t h e ope r a t i o n i s e s t a b l i s h e (3 a n d c h e c k e cl 
f or va l id cornp l e t i on with a ’ 0 O' r e t urn c:o de , 

SEQDSK 

0 0 

recorels ma y be wr i 1ten to the disk e11e f i l e . 

An i n t e ger r e cor cl i s wr i t1 en f i r s t , 

SEQDSK\ 3.0 


Always check the return code on output, 

SEQDSK 

0 0 

A P L IN T E R N A L. s e q u e n t i a l file s p e r m i t w r i t i n g o f 
any type of data within the same file, For 
e xamp l e , you c:an write a f l o a t i n g p o i n t r e c:o r cl , 

SEQDSK*. 5+\ 3.0 
SEQDSK 

0 l) 

a n d a hi n a r y r e c: o r cl, 

SEQDSK 15 p 0 3. 0 10 11 
SEQDSK 

0 0 

a n (3 a c: h a r a c t e r r e c: o r cl. 

SEQDSK ' Th i s is t h e LAST r e c o r d . ' 


0 0 


same 


SEQDSK 



You (::a n n o w c l o s e t h e f i l e , 


SEQDSK *- \ 0 
SEQDSK 

0 0 

and r ead wha t was wr i tt en t o the cl i sl< e tt e . 

N (!) T E t h a t o n l y t h e ID ( o r D ey ice/ F i l e N u rn b e r ) i s 
n e e de d t o sp e c i f y a da t a f i l e on t h e cl i s k e t l - e . 

SEQDSK*- ’ IN ID= < TEST) * 

C h e c: l< t h e r e t u r n c o cl e . 

SEQDSK 

0 0 

a n cl r e a cl e a c h r e c o r cl i n t h e o r cl e r t h a t i t 
was written, 

F i r s t, t h e i n t e g e r r e c: o r cl, 

SEQDSK 

1 2 3 4 5 6 7 8 9 10 

t h e f I oat i n g p o i n t r e c: o r cl, 

SEQDSK 

1 .5 2.5 3,3 4,5 5,5 6 ,5 7 ,5 8,5 9.5 10 ,5 

t h e b i n a r y r e c: o r d, 

SEQDSK 

0 1 0 1 0 1 1 0 1 0 1 0 1 1 0 

a n d, fin a l ly , t h e c I i a r a c: I - e r r e c o r d , 

SEQDSK 

Th i s i s t h e LAST r e c: o r cl, 

T l "i e r e w ill n o w b e a n e m p t y v e c t o r r e t u r n e d , 

which indicates the end of data or an I/O error, 

SEQDSK 

C h e c: l< f o r a n e r r o r c: o n cl i t i o n . 

SEQDSK 

0 0 

A ' 0 0 ' r e t ur n c: o cl e i n cl i c: a t e s that 1 1 , «.■ r e 
is no more data. 
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G E N E R A I.., E X i: H A N G E (E i l e t y p e 2 ) f i l e s a r e h a n d l e d 
t h e s a rn e a s A P L IN T E R N A L f i l e s e x c e p t t h a t all d a t a 
must be in character format. This type of file may 
be exc:hange d w i th the BASIC i...anguage . 

Both GENERAL EXCHANGE and A PL INTERNAL format- 
files may he written to tape in a similar fashion 
a n d b o t h a r e c: o mp a t i b l e w i t h t h e IBM 5 1 0 0 . 

In addition, The 5 11 0 will r e a d 51 00 fi le t ypes 1 
a n d 3 . 
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RECORD I/O *# 


1 OB VO * CTLDSK * 

9 

A*. 

1 QSVO 'DATDSK* 

9 


T w o s h a r e d variable s a r e offer© cl w h i c: h c: a n b e 
used to g e t h e r f o r r e c: o r d i n p u t / o u t p u t . 

CTLDSK*-' OIJTF 11001 ID"-(TEST) ' 


CTLDSK 

0 0 


A s s i g n m e n t s t o C T L D S K u r i t e r e c: o r cl s o n to the diskette 
The records must all be the same length and internal 
r e p r e s e n t a t i o n s i n c e t h e s e a r e d e f a u It T Y P E :::: A r e c: o r cl s 


CTLDSK*!0 0 p'A' 


CTLDSK*!00 p'B' 
CTLDSK*!0 0 p’C' 
CTLDSK*!00p ' D' 


CTLDSK *•! OOp’E’ 


CTLDSK*!0 0 p 'F 


P TI T'l C |< i- 9 ft 0 ' ft ' 

10 STATUS! INVALID DATA TYPE 

CTLDSK*- ISOp’H' 

IO STATUS: INVALID DATA TYPE 


CTLDSK* !0 0 pi 

10 STATUS: INVALID DATA TYPE 

N 0 T E t h a t t h e a s s i g n m e n t m u <r> t b e c: l i a r a c t e r a n cl t h e 
length must be 100 since that is true with the first 
r ecor d , The err or meissages wer e d i sp layed bec:ause 
th e MS(;) 01- F parame ter uas no t s p e c: i f i e d . 
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CTLDSK \ 0 


CTLDSK 

0 0 


Th e o u t 1 " 1 u t o p e r a t ion i s n o w t e v m i ri a t e d . 

N o r rn ally, y o u w o u l d w a n t t o c h e c i< r e t u r n c: o d e s 

t o a s s u v e p r o p e r o p e r a t i o n . i :: ' o r e x a m p l e , 11R C 0 D E 

s h o u Id at w a y s b e 0 w i t h r e c o r ci i n p u t / o u t p u t 

CTLDSK*■ 1 10R :l. :l. 0 () :l. ID= (TEST) * 

The file is now being specified for input or output 
o p e r a t i o n s . 


Y o u c o u l d in a v e u s e d IN R.t o R E A D 0 N L Y 

or IORH.-to READ or WRITE. 

10 R a n d I (!) R H d i f f e r i n s t o r a g e r e q u i r e m e n t s a n d 
P e r f o r m a n c e . T h e y a r e t h e s a m e i n f u n t i o n . 


0 6 


CTLDSK 

N 0 T E t h a t t h e r e a r e 6 r e c: o r d s a v a i l a b l e . 

A l l r e a d s a n d wr i t e s m u s t a (.1 (.1 r e s s o n e o f t h e in e 
actual records. 

T o a d d r e c o r ds t o a r e c o r d I /Q f i l e o r i y i n ally 
c r e a t e d u s i n g 0 U T F, y o u m u <;> t <;> p e c i f y a n A D D 
o p e r a t i o n . 


CTLDSK will now be used to read and write and 
I 1 A T D S K i s t h e m a r i a b l e c o ri t a i n i n g t h e d a t a . 

CTLDSK*-A B C 


t t t NUMBER OF RECORDS TO READ OR WRITE 

t t ..FIRST RECORD TO READ OR WRITE 

t .READ OR WRITE (READ-0 AND WRITE-!) 


CTLDSK*0 0 

T h i s s a y s t o r e a d t h e f i r s t r e t: o r d ( R E C 0 R D 0 ) a n d 
r e a d o n l y o n e r e c o r (i w h i c h i s t h e d e f a u 11 f o r 
t h e n u m !:• e r o f r e c o r d i:> 


pDATDSK 

10 0 
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DATDSK E: :l. 2 3 5!] 


AAA A A 

GTLDSK<- 0 i 3 

y o u h a v r o a cl 3 r (•? c c» r ds i;> t a r 1' i n g w i t h l - h e s e c o n d o n e 
PDATDSK 

3 10 0 

DATDSK i:; 1 2 3 M li 

BBBB 

CCCC 

DDDD 

DATDSK10 0 p ' Z ' 

CTLDSKfl 1 

No w y o u h a v <■> ur i + i en a n e uj c:on cl r c:o v d c: on t a i n i n g 
10 0 Z ' S . T o c:h o> c:l< y o u ca n r e r e a d t h e f i r s t l- h r e c> . 

CTLDSKi- 0 0 3 
pDATDSK 

3 100 

DATDSK i:; 1 2 3 »-i-II 

AAA A 
ZZ 2 . 7 . 

CCCC 

CTLDSK<- \ 0 

T h i s t e r m i n a t c s t h <•? i n p u t / o u t p u. t o p e r a t i o n s , 

CTLDSK 

0 0 
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USING THE )RESUME COMMAND 


There might be times when you are using a user-defined function to 
do I/O operations and you want to stop the I/O operation until a later 
time. If you suspend the user-defined function by pressing ATTN once 
{a weak interrupt) and then write the contents of the active workspace 
to the media using the )CONTINUE command, you can use the 
)RESUME command to load the stored workspace into the active 
workspace and reestablish the system as it was. That is, the shared 
variables and suspended function are reestablished in the active 
workspace, and, if you enter -► DLC the user-defined function 
continues execution from the point where it was suspended. 

Note: When you use the )RESUME command, you must make sure 
that the tapes or diskettes are correctly positioned. See the IBM 5110 
APL Reference Manual for a complete description of the )RESUME 
command. 


MORE ABOUT RECORDS AND FILES 


The basic unit of organized data is the record. A record is a collection 
of related data items that are treated as a unit. For example, the 
driver's license most of us carry is a record. A time card is also a 
record. Each record contains items related to the purpose of the 
record. The related items are called fields. The following illustration 
shows a record containing the fields of information that might be 
found on a driver's license: 


Drivers Name 


Address 


X 




License No. Eyes 

Date of Birth \ Height \ Sex 

— \ , \ xX i 


ROBERT JAMES 13 FORE AVE. ANYTOWN, N.Y. 


9-30-42 


132-5711 


5-9 


BR 


M 




Each field in the previous record contains information relating to a 
specific driver. The length of the field is the maximum number of 
characters that is to be placed in the field. The next illustration shows 
a record containing the fields of information that might be found on a 
time card: 


Name 


Location 


Date Serial No. Shift Start Time 


TOM ROBERTS 


ENDICOTT 


10-10-74 


83215 



1:00 


A group of records make up a file. Just as a filing cabinet contains a 
number of records in some specific sequence, a 5110 data file also 
contains records in some specific sequence. 


The following illustration shows a record containing customer 
information that would be used in making out an invoice: 


Customer 


Name 


Street 


City, State 


numbers. A file should be given a unique name so that the file can be 
distinguished from other files. Because the record in the previous 
illustration contains customer master information, the file could be 
named CUSTOMER.MASTER. A file containing master information 
about the products in your inventory could be named ITEM.MASTER. 


Billing 


Number 

v_ 

\ 

Address 

\ 

/ 

C 

/ 


\ 

137250 

\ 

JAMES CONSTRUCTION CO. 

\ 

13 TOPPER AVE 

TROY, N.Y. 

r 

13 

The file would contain as many records as there are customer 


Different files can contain different record layouts. For example, the 
following illustration shows a record that has items related to the item 
file: 


Item Qty in 

Number Description Price Stock 

\-r -l -r—A—/ 


874164 


WIDGET 


13.95 


0043 
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Organizing a Diskette File 

An important part of any data processing job is file organization. File 
organization is the arrangement of records in a file. 


Sequential Access Files 

Sequential access files are processed consecutively. For example, an 
employee master file contains information needed for various reports 
concerning each employee, such as payroll checks. Because checks 
are usually processed in order by employee number, records are 
processed in order. The lowest employee number is processed first 
and so on until the last record, the highest employee number, is 
processed. 

Sequential processing means records are processed one after another 
in the order they occur in the file. To process only certain records all 
records must be processed, or at least read up to the last record to be 
processed. 



Direct Access Files 


Since sequential processing can be time consuming, it would be 
helpful if diskette records were available like books in a library. That 
is, you could go to an index, find the location where the book is 
stored, go to the right shelf, and get the book you want. No one 
would read all the books in the shelves before reading the desired 
book. Likewise, it would be desirable to skip the records not needed 
in a job and process only the desired ones. Because direct access 
files allow specified records to be processed by record number, the 
limitation of sequential processing can be overcome by an index. 

To create and use an index, you could use the following procedure: 

1. As you create the direct access, you also create a matrix with 
each row representing a key field in the record. For example, the 
first 7 characters in a record are the item number. As you write 
a record to the file, you also add the item number to a matrix of 
item numbers. 

2. Now, when you want to directly access a record by record 
number, you can find the record number by using the following 
user-defined function {assuming DIO-HD): 

VZH..IST INDEX 1 TEN 

I" 1 "I Z f- < < L 1 S T A . :::: < ~ :l. f p |„, IS T ) f IT E M) ) / 11 f p LI $ T V 

The explicit result of this user-defined function is the row of the 
matrix that contains the specified item number. This explicit 
result also identifies the record number of the specified item 
number in the data file. 

3. Once you find the record number of the specified item number, 
you can directly access and process that record without regard to 
its relation to other records. 
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Ordered and Unordered Records 


The records in a direct access file can be ordered or unordered. An 
ordered file means that the records are arranged in order according to 
some major control field or by frequency of use. An unordered file 
means that the records are not in any particular order. 

With a 5110, it takes less time to specify and read 100 records at one 
time than to specify and read individual records 100 times. Therefore, 
arranging your records in order of frequency of use might save you 
processing time. For example, a wholesale distributor organizes the 
file of inventory items by frequency of use. Thus, the most active 
items are at the beginning of the file. Then, when the file is used to 
write customer orders, most of the records are located in a small area 
of the file and can be processed as multiple records. In this example, 
the total time to process the orders is less than if the records were 
scattered throughout the entire file. 


Maintaining Diskette Files 

Once a file is created, file maintenance is often necessary. File 
maintenance means performing those activities that keep a file current 
for daily processing needs. Some file maintenance activities are: 
adding, deleting, and updating records. Adding means putting a 
record in a file after the file is created. Deleting means identifying a 
record so it will not be processed with other records. Updating means 
adding or changing some data in a record. 


Adding Records 

Records can be added at the end of a file after a file has been 
created. Thus, the file is extended by the added records. 

Sometimes, however, the new records must be merged between the 
records already in the file. This might be necessary to keep the file in 
a particular order when the control fields of the new records are not 
higher in sequence than those already in the file; for example, when 
you are using the file for search by key operations. To put the new 
records in the proper sequence, you must use an APL user-defined 
function to sort the file and create a new file containing the added 
records or use the Diskette Sort feature if installed. See the IBM 5110 
Customer Support Functions Reference Manual, SA21-9311, for more 
information on the Diskette Sort feature. 



Tagging Records for Deletion 


When a record becomes inactive, you might not want to process it 
with the other records. A record cannot be physically removed from 
the file during regular processing; therefore, it is necessary to identify 
or tag the record so it can be bypassed. One way to tag such a record 
is to put a code, called a delete code, in a particular location in the 
record. When the file is processed, your user-defined function can 
check for the delete code; if the code is present, the record is 
bypassed. 


When several records in a file have been tagged for deletion, you 
should remove them from the file. This will free diskette space. You 
can remove the deleted records by using a user-defined function to 
copy the records to be retained onto another file or write new records 
over the deleted records. 


Updating Records 

When you update records in a file, you can add or change some data 
on the record. For example, in an inventory file you might want to 
add the quantity of items received to the previous quantity on hand. 
The record to be updated is read into storage, changed, and written 
back in its original location. 


Designing a Record 

The applications that use a certain file determine what data is needed 
in a record. You should study these applications and then decide the 
layout of the record. Layout means the arrangement of fields in a 
record. When you design a record, you must consider processing 
requirements of the record and then determine field length, location, 
and name. 

A name and address file is used to illustrate these design 
considerations. Each record in the file contains the following data: 

Size (number of characters) 

8 

20 
20 
20 
2 
1 

(total) 47 
Total 116 


Field 

Customer Number 
Name 

Street Address 
City and State 
Record Code 
Delete Code 
(Other fields) 
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Determining Field Size 


Field size depends on the nature of the data in the field. First, the 
length of the data may vary. In the example, name is 20 characters. 
The length of each customer's name varies, but 20 characters should 
be sufficient for all names. Secondly, all data in a field might be the 
same length. For example, customer number is eight positions, and all 
eight positions are used in each record. 

There are no firm rules for determining field size. The major problem 
involves fields with variable length data. For example, if a name is 
planned as 15 characters, and a new customer has 19 characters in his 
name, a problem arises when you add his record to the file. To avoid 
this problem, try to estimate the largest length of data that will be 
contained in a field. Use this length to determine the field size. 


Providing for a Delete Code 

Remember that records are not automatically deleted. You might want 
to place a delete code in a record, and then when the file is processed 
you must check for the delete code. In the example, if a customer 
becomes inactive, we do not want to process his record. Thus, a 
one-position field is included to provide for a delete code. 

Of course, if you are using an index to find the records in a direct 
access file, you do not need a delete code. Instead, you can remove 
the record key from the index. See Organizing a Diskette File in this 
chapter for information on creating an index. 


Providing Extra Space 

At this stage in planning, it is often wise to allow for data to be added 
to a record. For example, suppose the name and address file was 
created with the fields described, and at a later time each customer's 
zip code is needed. If all positions in the record are used, there is no 
place to add the zip code. Because the record length is not yet 
established, we can allow for such additions to this record. Although it 
is often difficult at the planning stage to imagine what data might be 
added, it is wise to reserve extra space. A minimum of 10% extra 
space is suggested. 



Documenting Record Layout 


When record layouts are documented, your APL user-defined function 
might be easier to write. A record layout should include the order of 
the fields in the record, the length of each field, and the name of each 
field. The following illustration shows the layout of a customer master 
record: 


Customer 

Number 


~r 

Name 

Street Address 

City and State 


: {f 

-telds 


Other Fields \ \ Reserved Space 


L-'CICIC 

Code 

'/l 


127 128 


In the previous example, the sum of the fields is 116 positions. 
However, the record size is 128 positions, thus reserving 12 positions 
for data that might be needed at a later time. 


Determining the Number of Records in a File 

When determining the number of records in a file, you should consider 
expansion for a reasonable time into the future (at least six months). 
Then when you create the file, if you place dummy records in the file, 
these dummy records can then be replaced with valid records at a 
later time. Of course, you can also add records to the file using an 
ADD operation. 
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Chapter 11. Debugging and Error Recovery Techniques 


SUSPENDED FUNCTION EXECUTION 

The execution of a user-defined function can be interrupted 
(suspended) in a variety of ways: by an error message, by pressing 
the ATTN key, or by using the stop control vector (SA). In any case, 
the suspended function is still considered active, since its execution 
can be resumed. Whatever the reason for the suspension, when it 
occurs, the statement number of the next statement to be executed is 
displayed. A branch to the statement number that was displayed or a 
branch to DLC^DLC) causes normal continuation of the function, and 
a branch out (->-0) removes the function. 

When a function is suspended, the 5110 will: 

• Continue to execute system commands except )SAVE, )COPY and 
)PCOPY. 

• Resume execution of the function at statement n when -*n is 
entered. 

• Reopen the definition of any function that is not pendent. A 
pendent function is a function that called the suspended function. If 
a function called a function that called a suspended function, it is 
also pendent (see State Indicator). 

• Execute other functions or expressions. 

• Execute the suspended function again. 

Note: The display of output generated by a previous statement might 
have been interrupted when the suspension occurred. This would be 
caused by the delay between execution of the statement and display 
of the output. 
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STATE INDICATOR 


The state indicator identifies which functions are suspended (*) and at 
what point normal execution can be resumed. Entering )SI causes a 
display of the state indicator. Such a display might have the following 
form: 


>SI 

hi: 73 * 

Gi:2:i 
F i:3:i 

This display indicates that execution was halted just before statement 
7 of function H, that the current use of function H was invoked in 
statement 2 of function G, and that the use of function G was invoked 
in statement 3 of F. The * appearing to the right of H[7] indicates that 
function H is suspended; the functions G and F are said to be 
pendent. 

During the suspension of one function, another function can be 
executed. Thus, if a further suspension occurred in statement 5 of 
function Q, which was invoked in statement 8 of G, a display of the 
state indicator would be as follows: 

>51 

Q i:5:i * 

Qi:e:i 

hi: ?:i * 

01:2:1 
f 1:3:1 

An SI DAMAGE error indicates that a suspended function has been 
edited or a pendent function has been erased and the normal 
execution of the suspended function can no longer be resumed. When 
an SI DAMAGE error occurs, the state indicator display will include the 
damaged function name and the statement number 1. For example, if 
function Q is edited and the modification causes an SI DAMAGE error, 
the display of the state indicator would be as follows: 

>s:i: 

q 1:" :i. ::i * 

01:0:1 
hi: 7:1 
01:2:1 
f 1:3:1 
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You can clear a suspension by entering a branch with no argument 
(that is, -*). One suspended function is cleared at a time, along with 
any pendent functions for that suspended function. The first branch 
clears the most recently suspended function, as in the following 
example: 


)s:i: 

•M 


01:2:1 


It is a good practice to clear suspended functions, because suspended 
functions use available storage in the active workspace. Repeated use 
of -* clears all the suspended functions; as the functions are cleared, 
they are removed (cleared) from the state indicator. When the state 
indicator is completely cleared, the state indicator display is a blank 
line. 

Note: To display the state indicator with local names, enter the )SINL 
command. 
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Appendix A. 5110 Compatibility with Other APL Systems 


The foilwing user-defined functions are example functions that can be 
used to check 5110 user-defined functions for compatibility with other 
APL systems: 


i:: :l :i 
i::2::i 
1133 
dmi 


y check cony 

y C H E C K F; E A; E L; C F.; F Lj E D ; 0I0 ; o P W 
a CHECK F(.1E P0SSIBLE INCDM PATIBILITES IN FUNCT10N 
fl E E :::: E R R 0 R A R R A Y G L :::: C 0 L U M N E D G E N D 

ft R F « R 0 U F L A G 8 < E R R 0 R 8 ) 

010*1 


RL=R0W LEDGEND 



13 

23 

33 

rmii 

53 

63 

73 

C8II 


' Z +PORTABL 
ft RETURN A 
ft''OCR F'' 


cf; cs;oio 

0GZCAL MATRIX <ONES AND ZEROS) THE SAME SHAPE AS 
“A 1 INDICATES CHANGES REQUIRED FOR PORTABILITY 


ft C S ~ L E G A L C H A R A C T E R S E 1 
010*1 

CS*0AV[; < 1 >•!• * \ 9) 

Z*«CF«CS 
Z*Zv(CF™'o') 

Z*Zv('i 0SV0* 


CF-CHAR MATRIX OP 
< 25* x 5M-) , ( 86+ x 71) , .1.59,160,161 3 


WHEREIN CF) 


C93 

Z*Zv<’occ■ WHEREIN 

CF) 

C 1 0 3 

Z*Zv<’DAI' WHEREIN 

CF > 

L 11. 3 

Z*Zv( ’ [ITS ’ WHEREIN 

CF) 

II123 

Z*Zv('0TT' WHEREIN 

CF) 

11133 

Z*Zv< ' 0UL..' WHEREIN 

CF) 

cm 3 

Z + Zv ( [|DL * WHEREIN 

CF) 

y 

s' 



yWHE RE INC in ny 


y 

Z+A WHEREIN B;QI0 


II13 

ftLOCATION OF VECTOR 

A Ii 

[.23 

01 o + o 



ARRAY B 


L33 Z*< (-ppB)tl) Ia/L: 03(N( ( "llpB) , pA)px pA)c|)0 , (A*, A)* . 
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VTESTFUNCTI0NCQ3V 

V TESTFUNCTION 

5 occ 20 

1 : 2:1 1 . osvo 'A 1 

V 


CHECK ’TESTFUNCTION’ 
1 ;:0:J TESTFUNCTION 

* d3 5 OCC 20 

t 

■K- 1 : 2:1 1 OS VO ‘ A 



These statements might not 
be compatible with another 
APL system. 



JCONTINUE command 69 
)COPY command 46 
)DROP command 76, 88 
)ERASE command 138 
)FILEID command 87 
)FNS command 48 
)FREE command 90 
)LOAD command 45 
)MARK command 75, 88 
)OUTSEI. command 95 
)PCOPY command 46 
)PROC command 46 
)PROTEC'T command 73, 87 
)RESUME command 45, 146 
)SAVE command 69 
)SI command 48 
)SINL command 48 
)SYMBOLS command 48 
)VARS command 48 
)VOLID command 73, 85 
)WSID command 48 
□CC system function 62, 95 

□ EX system function 138 

□ LC system function 155 

□ PP system variable 95 

□SVO system function 117 
□SVR system function 138 
-►□LC 155 

v function 95 


access-protect indicator 82 
active workspace 3, 75 
active workspace control 41 
add data to an existing file 121 
ADD operation 79, 121 
adding records 150 
APL 4 

APL commands 5 
APL expressions 5 
APL internal code 114 
APL internal format 109,111 
APL shared variable 95, 117 
APL user-defined function 4 
application 5 
arrays 16 

assignment arrow 13 
atomic vector 115 
audible alarm 64 


beginning of extent (BOE) 84 
BOE 84 
bytes 75 



catenation 25 

arrays of unequal sizes 26 
matrices 25 
scalars to arrays 26 
vectors or scalars 25 
vectors to arrays 26 
center character string in matrix row 35 
changing workspace environment 43 
character constants 15 
character position 134 
clear suspended functions 157 
CLEAR WS environment 42 
complex name 87 
compress data 79 
console control 65, 97, 101 
console storage 59 
CONTINUE 69 
controlling display screen 63 
controlling files 72 
convert to a matrix 105 
COPY 46 

count unique characters in vector 35 

create a data file 119 

create a matrix from a vector 31 

creating lists 27 

CTL DOMAIN ERROR 132 

CTL shared variable 124 

cursor return character 110 


DAT shared variable 124 
data 1 

data cartridge 75 
data file 

create 119 
direct access 108 
formats 109 
sequential access 108 
data files 75 
data processing 2 
data representation 14 
data security 73 
data types 50 

data written to the data file 120 
debugging 155 
degree of coupling 117 
delete code 151 

delete comment lines from a function 32 

delete duplicate elements 33 

delete function names 34 

delete leading blanks 38 

delete name from list 39 

deleted records 151 

deleting records 150 

designing a record 151 

determining field size 152 

determining size of file 68 

direct access data file 108, 119 

diskette 3, 6, 81 

diskette addressing 83 

diskette drive 81 

diskette files 

organizing 148 
maintenance 150 
diskette formats 85 
diskette initialization 81, 86 
diskette sort feature 150 
diskette storage 54 
diskette volume ID 82 
display screen 4, 7, 63 
read from 133 
write to 133 

documenting record layout 153 
DROP 76, 88 
drop blanks 102 
drop blanks and periods 102 
drop extra blanks 105 
drop leading blanks 102 
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EBCDIC code 114 

empty arrays 21 

end of block character 110 

end of data (EOD) 84 

end of extent (EOE) 84 

EOD 34, 84 

EOE 84, 102 

ERASE 138 

error recovery 155 

establishing an APL shared variable 117 


fields 146 
file headers 75 
file ID 87 
file maintenance 

adding records 150 
deleting records 151 
updating records 151 
file organization 146 
FILEID 87 

find first nonblank character 33 

find index of name 103 

find location of name in list 39 

FNS 48 

format 6 

format 

APL internal 109,111 
function 95 

general exchange 109, 111 
mixed 113 
nontranslated 114 
unblocked and unspanned 112 
formatting reports 98, 101 
formatting tape 75 
FREE 90 


general exchange format 109, 111 
generate a matrix 18 
generating arrays 17 
getting information from a file 71 


hard copy output 4 
helpful functions 102 
convert to a matrix 105 
drop blanks 102 
drop blanks and period 102 
drop extra blanks 105 
drop leading blanks 102 
find index of name 103 
insert blank lines 104 
join two variables 106 
left-justify 103 
print a matrix 104 
replace periods 102 


I/O processor 116 
IN operation 122 
index cylinder 84 
index file 149 
index track 90 
indexing arrays 22 
initialization, diskette 81, 86 
input 2 

input/output operations 118 
INR operation 132 
insert blank lines 104 
interface 12 

INTERFACE QUOTA EXHAUSTED 117 

internal precision 96 

internal storage 3 

IOR operation 125 

IORH operation 125 


join two variables 106 

join vectors and print results 38 

joining arrays 25 


key value 131 
keyboard 3, 7, 60 
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laminated records 127 
lamination 28 
language elements 13 
left justify 103 

left-justify character string in matrix 36 

library control 67 

list each function in workspace 36 

list each variable in workspace 37 

LOAD 45 

logical data 15 

logical record 108 

lowercase characters 60 


maintaining diskette files 150 

make scalar or vector into a matrix 34 

MARK 75, 88 

MAT PUT statement 109 

matrices 16 

merge two variables 33 

mixed format 113 


negative sign 14 
nontranslated format 114 
number of records 126 
number of records in the file 153 
numbers 14 
numeric precision 14 
numeric value range 14 


operations 

ADD 79, 121 
INR 132 
IOR 125 
IORH 125 
OUT 78 
OUTF 119 
PRT 137 

operations to be performed 118 
ordered file 150 
ordered records 150 
organizing a diskette file 148 
OUT operation 78, 119 
OUTF operation 119 
output 2 
output format 95 
OUTSEL 95 


pair of shared variables 124 

PCOPY 46 

pendent function 155 

perform operation on conditions 40 

physical record 108 

precision 

internal 96 
printed 96 
print data 137 
printer 3 
printing data 95 
PROC 46 
procedure file 46 
process 2, 8 
program 1, 12 
PROTECT 73, 87 
providing extra space 152 
PRT operation 137 
PUT statement 109 


quotes 
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random access 77 

rank of an array 19 

read a data file 122 

read direct 108,119 

read from the display screen 133 

read multiple records 127 

read records 126 

read sequentially 122 

read/write head 82 

read-only a data file 132 

record 146 

records 

laminated 127 
ordered 150 
unordered 150 
updating 124 
designing 151 
fields 146 
layout 151 
logical 108 
numbering 126 
physcial 108 

remove alpha characters from vector 32 

remove duplicate blanks from a vector 31 

replace periods 102 

replace trailing blanks 32 

report formatting 98, 101 

reshape function 17 

RESUME 45, 146 

resume execution 155 

retracting the shared variable 138 

return code 120, 123 

return even numbered elements 32 

right-justify character string in matrix 35 


SA 155 

SAFE switch 73 

sample input/output operations 140 
SAVE 69 
scalars 16 

scaled representation 14 

scientific notation 14 

search by key 126, 131 

search file for a specific record 131 

sector 84 

security 73 

sequential access 77 

sequential access data file 108, 119 

sequentially read 122 


shape of array 17 
shared variable 95, 117 
shared variable offer 117 
shared variable pair 124 
SI 48 

SI DAMAGE 156 
simple name 87 
SINL 48 

sort columns of matrix 39 
sort feature 150 

specifying the operation to be performed 118 
starting character number 134 
starting record number 126 
state indicator 156 
stop control 155 
storage considerations 49 
storage diskette 54 
storage, internal 3 
suspend I/O operations 146 
suspended functions 155 
symbol table 43 
SYMBOLS 48 
system 3 
system commands 
CONTINUE 69 
)COPY 46 
)DROP 76,88 
)ERASE 138 
)FI LEI D 87 
)FNS 48 
)FREE 90 
)LOAD 45 
)MARK 75, 88 
)OUTSEL 95 
)PCOPY 46 
)PROC 46 
)PROTECT 73, 87 
)RESUME 45, 146 
)SAVE 69 
)SI 48 
)SINL 48 
)SYMBOLS 48 
)VARS 48 
)VOLID 73 
)VOLID 85 
)WSID 48 
system functions 
□CC 62, 95, 97 
□EX 138 
□SVO 117 
□SVR 138 

system variable DPP 95 


Index 165 



tape 3, 6 

tape storage 75 

terminate the operation 121, 138 

track 83 


unblocked and unspanned format 112 

unordered file 150 

unordered records 150 

update a data file 124 

updating records 124, 150 

useful statements and functions 31, 102 

user-defined functions 3 


variable name 13 
variables 13 
VARS 48 
vectors 16 
VO LID 73, 85 
volume ID 54 


weak interrupt 146 
workspace environment 43 
workspace files 75 
workspace ID 44 

workspace required for I/O operation 53 

write data 120 

write multiple records 127 

write records 126 

write to the display screen 133 

write-protect indicator 82 

writing data to a file 69 

WSID 48 


5110 data files 108 
5110 I/O processor 116 
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